{ "openapi": "3.0.3", "info": { "version": "3.0.0", "title": "Vertt AI", "description": "API docs dos serviços de IA da Convert Company, incluindo chat completions, transcrições de áudio, sumarizações, text-to-speech, agents com tool calling, bases de conhecimento com RAG (Retrieval-Augmented Generation), embeddings vetoriais e sistema de arquivamento de dados históricos. Versão 3.0.0 - Hand in Hand." }, "servers": [ { "url": "https://vertt.ai/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Audio", "description": "Dados sobre audio" }, { "name": "Completions", "description": "Operações relacionadas a completions" }, { "name": "Agents", "description": "Completions com tool calling, tracking de sessões e sistema de créditos" }, { "name": "Summarization", "description": "Operações relacionadas a sumarizações/análises/resumos" }, { "name": "Models", "description": "Listagem de modelos IA disponíveis" }, { "name": "ChromaDB - Databases (Admin)", "description": "Gerenciamento de databases ChromaDB (requer permissão admin)" }, { "name": "Knowledge Bases", "description": "Gerenciamento de bases de conhecimento com RAG (Retrieval-Augmented Generation), chunks de documentos e busca semântica" }, { "name": "Embeddings", "description": "Geração e consulta de embeddings vetoriais" }, { "name": "Documents", "description": "Monitoramento de jobs de processamento de documentos" } ], "paths": { "/v1/transcriptions": { "post": { "summary": "Transcrever um áudio", "operationId": "transcribeAudio", "tags": ["Audio"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["audio", "model"], "properties": { "audio": { "oneOf": [ { "type": "string", "format": "binary", "description": "Arquivo de áudio (mp3, wav, ogg)" }, { "type": "string", "format": "uri", "description": "URL pública apontando para arquivo de áudio" } ], "description": "Arquivo de áudio ou URL para transcrição. Tamanho máximo: 25MB. Formatos aceitos: mp3, wav, ogg" }, "model": { "type": "string", "description": "Modelo de transcrição disponível e ativo (consulte GET /v1/models/transcriptions)" }, "prompt": { "type": "string", "maxLength": 255, "description": "Texto opcional para auxiliar na transcrição", "nullable": true }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "description": "Controla aleatoriedade da saída (0-1)", "nullable": true } } } } } }, "responses": { "201": { "description": "A transcrição de áudio é a seguinte: ", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "A transcrição de áudio é a seguinte: " }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object", "properties": { "task": { "type": "string", "example": "transcribe" }, "language": { "type": "string", "example": "portuguese" }, "duration": { "type": "number", "example": 6.78 }, "text": { "type": "string", "example": "Conversação transcrita aqui" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 0 }, "seek": { "type": "number", "example": 0 }, "start": { "type": "number", "example": 0 }, "end": { "type": "number", "example": 2 }, "text": { "type": "string", "example": "Chunks do texto transcrito" }, "tokens": { "type": "array", "items": { "type": "integer" }, "example": [ 50364, 4935, 64, 11, 2119, 1515, 945, 2604, 27179, 13458, 30, 50464 ] }, "temperature": { "type": "number", "example": 0 }, "avg_logprob": { "type": "number", "example": -0.5864704847335815 }, "compression_ratio": { "type": "number", "example": 0.8048780560493469 }, "no_speech_prob": { "type": "number", "example": 0.06502998620271683 } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "Buscar transcrição", "tags": ["Audio"], "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "integer", "description": "O ID do cliente a ser filtrado" } } ], "responses": { "200": { "description": "Rota para obter transcriptions realizadas via Assembly model: ", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Os dados de transcript obtidos são" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "854215asf-3949fkkg-pqoelr30" }, "language-model": { "type": "string", "example": "assemblyai_default" }, "acoustic-model": { "type": "string", "example": "assemblyai_default" }, "language_code": { "type": "string", "example": "pt-br" }, "status": { "type": "string", "example": "completed" }, "audio_url": { "type": "string", "example": "https://audio.url.com" }, "text": { "type": "string", "example": "transcript aqui" }, "words": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "example": 0 }, "start": { "type": "number", "example": 0 }, "end": { "type": "number", "example": 2 }, "confidence": { "type": "number", "example": 3.2 }, "speaker": { "type": "string", "example": "1" }, "channel": { "type": "string", "example": "1" } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/completions": { "post": { "summary": "Criar Chat Completion", "tags": ["Completions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["messages", "model"], "properties": { "messages": { "type": "array", "description": "Array de objetos contendo os papéis (roles) que podem ser definidos para gerar uma conversação através da API de completions", "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ], "description": "O papel da mensagem na conversa" }, "content": { "type": "string", "description": "O conteúdo da mensagem" } } }, "example": [ { "role": "system", "content": "Você é um assistente cuja função será encaminhar usuários para setor 'x'" }, { "role": "user", "content": "Olá, preciso de ajuda com minha conta" } ] }, "model": { "type": "string", "example": "gpt-4o", "description": "O modelo a ser utilizado para as completions. Consulte /api/v1/models/completions para ver modelos disponíveis." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Valor numérico entre 0 e 2 que controla a aleatoriedade da saída." }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Número máximo de tokens a serem gerados na resposta." }, "response_format": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["json_object", "text"], "description": "Formato da resposta" } }, "description": "Força o modelo a retornar um JSON ou text" }, "parse_json": { "type": "boolean", "description": "Retorna um JSON parseado no conteúdo da completion" }, "tools": { "type": "array", "description": "Lista de ferramentas (function calling) disponíveis para o modelo", "items": { "type": "object", "required": ["type", "function"], "properties": { "type": { "type": "string", "enum": ["function"], "description": "Tipo da ferramenta" }, "function": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Nome da função" }, "description": { "type": "string", "description": "Descrição da função" }, "parameters": { "type": "object", "description": "Schema JSON dos parâmetros da função" } } } } } }, "tool_choice": { "type": "string", "enum": ["auto", "none", "required"], "description": "Controla quando e como as ferramentas são chamadas" }, "room_id": { "type": "string", "description": "ID da sala/conversa para agrupamento de interações relacionadas e tracking de conversação" } } } } } }, "responses": { "201": { "description": "Chat completion criada com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Chat completion criada com sucesso" }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object", "properties": { "response": { "oneOf": [ { "type": "string", "description": "Conteúdo da resposta quando parse_json=false" }, { "type": "object", "description": "Conteúdo da resposta como objeto quando parse_json=true" } ], "example": "Esta é a resposta da IA para sua pergunta." }, "prompt_tokens": { "type": "integer", "description": "Número de tokens utilizados na entrada (prompt)", "example": 25 }, "completion_tokens": { "type": "integer", "description": "Número de tokens utilizados na resposta", "example": 150 }, "total_tokens": { "type": "integer", "description": "Total de tokens utilizados (prompt + completion)", "example": 175 }, "tool_calls": { "type": "array", "description": "Chamadas de ferramentas realizadas pelo modelo (quando aplicável)", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID da chamada da ferramenta" }, "type": { "type": "string", "enum": [ "function" ], "description": "Tipo da ferramenta" }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da função chamada" }, "arguments": { "type": "string", "description": "Argumentos da função (JSON string)" } } } } } } } } } }, "examples": { "text_response": { "summary": "Resposta de texto simples", "value": { "msg": "Chat completion criada com sucesso", "status": 201, "data": { "response": "Olá! Como posso ajudá-lo hoje?", "prompt_tokens": 15, "completion_tokens": 8, "total_tokens": 23 } } }, "json_response": { "summary": "Resposta com parse_json=true", "value": { "msg": "Chat completion criada com sucesso", "status": 201, "data": { "response": { "answer": "Resposta formatada", "confidence": 0.95 }, "prompt_tokens": 25, "completion_tokens": 12, "total_tokens": 37 } } }, "function_calling": { "summary": "Resposta com function calling", "value": { "msg": "Chat completion criada com sucesso", "status": 201, "data": { "response": null, "prompt_tokens": 35, "completion_tokens": 15, "total_tokens": 50, "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"location\": \"São Paulo\"}" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "Obter completion por ID de billing", "tags": ["Completions"], "description": "Recupera uma completion específica usando o ID do registro de billing", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "description": "ID do billing da completion" } } ], "responses": { "200": { "description": "Completion recuperada com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Completion encontrada" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID do billing" }, "id_cliente": { "type": "integer", "description": "ID do cliente" }, "input_tokens": { "type": "integer", "description": "Tokens de entrada utilizados" }, "output_tokens": { "type": "integer", "description": "Tokens de saída gerados" }, "modelo_utilizado": { "type": "string", "description": "Modelo de IA utilizado" }, "api_utilizada": { "type": "string", "description": "API utilizada (completions, agents, etc.)" }, "response_id": { "type": "string", "description": "ID da sessão/conversa", "nullable": true }, "room_id": { "type": "string", "description": "ID da sala/conversa", "nullable": true }, "credits_spent": { "type": "integer", "description": "Créditos gastos", "nullable": true }, "from_reserve": { "type": "boolean", "description": "Se os créditos vieram da reserva" }, "created_at": { "type": "string", "format": "date-time", "description": "Data de criação" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/completions/responses/{response_id}": { "get": { "summary": "Obter completions por response_id", "tags": ["Completions"], "description": "Recupera todas as completions associadas a um response_id específico. Útil para tracking de sessões e conversas multi-turno.", "parameters": [ { "name": "response_id", "in": "path", "required": true, "schema": { "type": "string", "description": "ID da sessão/resposta para buscar todas as completions relacionadas" } } ], "responses": { "200": { "description": "Completions da sessão recuperadas com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Completions encontradas para response_id" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "description": "Lista de completions associadas ao response_id", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID do billing" }, "id_cliente": { "type": "integer", "description": "ID do cliente" }, "input_tokens": { "type": "integer", "description": "Tokens de entrada" }, "output_tokens": { "type": "integer", "description": "Tokens de saída" }, "modelo_utilizado": { "type": "string", "description": "Modelo utilizado" }, "api_utilizada": { "type": "string", "description": "API utilizada" }, "response_id": { "type": "string", "description": "ID da sessão" }, "room_id": { "type": "string", "description": "ID da sala", "nullable": true }, "credits_spent": { "type": "integer", "description": "Créditos gastos", "nullable": true }, "from_reserve": { "type": "boolean", "description": "Se veio da reserva" }, "created_at": { "type": "string", "format": "date-time", "description": "Data de criação" }, "tool_calls": { "type": "array", "description": "Tool calls associadas (se for agent completion)", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "tool_name": { "type": "string" }, "tool_parameters": { "type": "object" }, "tool_response": { "type": "object" } } } } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/agents/completions": { "post": { "summary": "Criar Agent Completion com Tool Calling", "tags": ["Agents"], "description": "Endpoint especializado para completions agenticas com suporte a tool calling, tracking de sessões via response_id e sistema de créditos. Permite que o modelo de IA invoque funções externas e retorne resultados estruturados.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["messages", "model"], "properties": { "messages": { "type": "array", "description": "Array de mensagens da conversa. Pode incluir mensagens de tipo 'tool' com resultados de chamadas de ferramentas anteriores.", "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": ["system", "user", "assistant", "tool"], "description": "O papel da mensagem. Use 'tool' para retornar resultados de tool calls." }, "content": { "type": "string", "description": "O conteúdo da mensagem ou resultado da ferramenta" }, "tool_call_id": { "type": "string", "description": "ID da tool call (obrigatório quando role='tool')" } } } }, "model": { "type": "string", "example": "gpt-4o", "description": "Modelo de IA a ser utilizado. Consulte /api/v1/models/agents para modelos disponíveis." }, "tools": { "type": "array", "description": "Lista de ferramentas (function calling) disponíveis para o agent", "items": { "type": "object", "required": ["type", "function"], "properties": { "type": { "type": "string", "enum": ["function"], "description": "Tipo da ferramenta" }, "function": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Nome da função" }, "description": { "type": "string", "description": "Descrição do que a função faz" }, "parameters": { "type": "object", "description": "Schema JSON dos parâmetros da função" } } } } } }, "response_id": { "type": "string", "description": "ID único da sessão/conversa para tracking de múltiplas interações e tool calls" }, "room_id": { "type": "string", "description": "ID da sala/conversa para agrupamento de interações relacionadas" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Controla aleatoriedade da saída (0-2)" }, "max_tokens": { "type": "integer", "minimum": 1, "description": "Número máximo de tokens a serem gerados" }, "use_credits_from_reserve": { "type": "boolean", "default": false, "description": "Se true, utiliza créditos da reserva caso os créditos regulares estejam esgotados" } } } } } }, "responses": { "201": { "description": "Agent completion criada com sucesso. Pode incluir tool_calls se o modelo solicitou execução de ferramentas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Completion gerada com sucesso" }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único da completion" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer", "description": "Timestamp Unix de criação" }, "model": { "type": "string", "description": "Modelo utilizado" }, "response_id": { "type": "string", "description": "ID da sessão/conversa" }, "credits_spent": { "type": "integer", "description": "Créditos gastos nesta completion (1-10 créditos por bucket de tokens)" }, "from_reserve": { "type": "boolean", "description": "Indica se os créditos vieram da reserva" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "description": "Resposta do modelo (pode ser null se houver tool_calls)" }, "tool_calls": { "type": "array", "description": "Chamadas de ferramentas solicitadas pelo modelo", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único da tool call" }, "type": { "type": "string", "example": "function" }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome da função a ser chamada" }, "arguments": { "type": "string", "description": "JSON string com argumentos da função" } } } } } } } }, "finish_reason": { "type": "string", "enum": ["stop", "length", "tool_calls"], "description": "Motivo do término da geração" } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/summarization": { "post": { "summary": "Analisar conteúdo", "tags": ["Summarization"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["messages", "objectives", "model"], "properties": { "messages": { "type": "array", "description": "Array de mensagens seguindo padrão OpenAI", "minItems": 1, "items": { "type": "object", "required": ["role", "content"], "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "developer" ], "description": "Papel da mensagem na conversa" }, "content": { "type": "string", "description": "Conteúdo da mensagem" }, "name": { "type": "string", "description": "Nome opcional do remetente" } } } }, "objectives": { "type": "array", "description": "Objetivos de análise que definem campos dinâmicos na resposta", "minItems": 1, "items": { "type": "object", "description": "Cada objetivo define um campo personalizado na resposta" } }, "model": { "type": "string", "description": "Modelo a ser utilizado. Consulte /api/v1/models/summarizations para modelos disponíveis.", "example": "gpt-4o-mini" }, "instruction_header": { "type": "string", "maxLength": 20000, "description": "Instrução adicional para o sistema (opcional)" }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "description": "Valor numérico entre 0 e 2 que controla a aleatoriedade da saída" }, "response_format": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": [ "json_object", "json_schema" ], "description": "Formato da resposta" } }, "description": "Força o modelo a retornar em formato específico" }, "tools": { "type": "array", "description": "Ferramentas disponíveis para function calling", "items": { "type": "object", "required": ["type", "function"], "properties": { "type": { "type": "string", "enum": ["function"] }, "function": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "parameters": { "type": "object" } } } } } }, "tool_choice": { "type": "string", "enum": ["auto", "none", "required"], "description": "Controla como as ferramentas são utilizadas" }, "room_id": { "type": "string", "description": "ID da sala/conversa para agrupamento de sumarizações relacionadas e tracking de conversação" } } }, "examples": { "basic_summarization": { "summary": "Sumarização básica", "value": { "messages": [ { "role": "user", "content": "Analise este texto: [seu texto aqui]" } ], "objectives": [ { "value": "summarize", "label": "Resumo", "description": "Crie um resumo conciso do texto" } ], "model": "gpt-4o-mini" } }, "advanced_analysis": { "summary": "Análise avançada com múltiplos objetivos", "value": { "messages": [ { "role": "system", "content": "Você é um analista experiente" }, { "role": "user", "content": "Analise este relatório de vendas: [texto do relatório]" } ], "objectives": [ { "value": "summarize", "label": "Resumo", "description": "Resumo executivo do relatório" }, { "value": "customer_satisfaction", "label": "Satisfação", "description": "Avalie a satisfação do cliente de 1 a 10" }, { "value": "action_items", "label": "Ações", "description": "Liste as principais ações recomendadas" } ], "model": "gpt-4o", "temperature": 0.3 } } } } } }, "responses": { "201": { "description": "Sumarização criada com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Sumarização criada com sucesso" }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object", "properties": { "summarize": { "type": "string", "description": "Resumo principal do texto", "example": "Resumo do texto analisado" }, "prompt_tokens": { "type": "integer", "example": 3234, "description": "A quantidade de tokens recebidos no input" }, "completion_tokens": { "type": "integer", "example": 340, "description": "A quantidade de tokens que o model retornou na resposta" }, "total_tokens": { "type": "integer", "example": 3574, "description": "O total de tokens somados" } }, "additionalProperties": true, "description": "Campos adicionais podem aparecer baseados nos 'objectives' definidos na requisição" } } } } } } } } }, "/v1/transcribeComplete": { "post": { "summary": "Transcrever e Sumarizar áudio", "tags": ["Audio"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["audio"], "properties": { "audio": { "format": "binary", "description": "Arquivo de áudio ou URL com link público a ser transcrito (mp3, wav, ogg). Tamanho máximo: 10MB. Exemplos: `audio.mp3, https://exemplo.com/audio.mp3`" }, "prompt": { "type": "object", "description": "Objeto JSON contendo campos extras de escolha do usuário para serem agregados ao retorno", "example": { "customer_satisfaction": "Nota de 1 a 10 contendo a satisfação do usuário com base no texto transcrito" }, "nullable": true }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "description": "Valor numérico entre 0 e 1 que controla a aleatoriedade da saída.", "nullable": true } } } } } }, "responses": { "201": { "description": "As informações de summarização criadas: ", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "As informações de summarização criadas: " }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object", "properties": { "text": { "type": "string", "example": "Texto passado no input da request" }, "resumo": { "type": "string", "example": "Resumo do texto" }, "keywords": { "type": "array", "items": { "type": "string" }, "example": [ "palavrachave1, palavrachave2" ], "description": "Palavras chaves encontradas no texto" }, "topics": { "type": "array", "items": { "type": "string" }, "example": [ "topico_importante1, topico_importante2" ], "description": "Descrição dos tópicos chaves encontrados no texto" }, "sentiment": { "type": "string", "example": "neutro,positivo,negativo", "description": "O sentimento identificado no texto" }, "prompt_tokens": { "type": "integer", "example": 3234, "description": "A quantidade de tokens de tokens recebidos no input" }, "completion_tokens": { "example": 340, "description": "A quantidade de tokens que o model retornou na resposta" }, "total_tokens": { "example": 3574, "description": "O total de tokens somados" }, "extras": { "type": "object", "example": { "customer_satisfaction": 8 }, "description": "Objeto que retorna os fields recebidos na request quando informados com suas respectivas características" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/textToSpeech": { "post": { "summary": "Criar text-to-speech", "tags": ["Audio"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["model", "input", "voice"], "properties": { "model": { "type": "string", "description": "O modelo a ser utilizado, exemplo: tts-1-hd", "default": "tts-1-hd", "enum": [ "tts-1-hd", "tts-1", "azure-speech" ] }, "input": { "type": "string", "description": "O texto a ser convertido para áudio. Caso o modelo selecionado for tts, o máximo é 4096 caracteres. Caso seja azure, 16000 caracteres", "example": "seu texto aqui" }, "voice": { "type": "string", "default": "onyx", "description": "As vozes disponíveis para os modelos da Open AI são: alloy,echo,fable,onyx,nova,shimmer. O restante com o prefixo pt-BR faz parte dos modelos da Azure.", "enum": [ "alloy", "echo", "fable", "onyx", "nova", "shimmer", "pt-BR-LeticiaNeural", "pt-BR-ManuelaNeural", "pt-BR-NicolauNeural", "pt-BR-AntonioNeural", "pt-BR-FranciscaNeural", "pt-BR-GiovannaNeural", "pt-BR-HumbertoNeural", "pt-BR-ValerioNeural", "pt-BR-YaraNeural", "pt-BR-BrendaNeural", "pt-BR-DonatoNeural", "pt-BR-FabioNeural", "pt-BR-ElzaNeural", "pt-BR-JulioNeural", "pt-BR-LeilaNeural" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4, "description": "Valor numérico entre 0.25 e 4.0 que controla a velocidade do áudio gerado (aplicável p/ modelos Open AI).", "nullable": true } } }, "examples": { "example1": { "summary": "Texto simples", "value": { "model": "tts-1-hd", "input": "seu texto aqui", "voice": "onyx", "speed": 1 } }, "example2": { "summary": "Texto com formatação SSML", "value": { "model": "azure-speech", "input": "Olá, como você está hoje? essa é uma das formas de testar o TTS com o SSML", "voice": "pt-BR-LeticiaNeural" } } } } } }, "responses": { "201": { "description": "Retorna o áudio gerado", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/clientes": { "get": { "summary": "Listar clientes cadastrados (Admin)", "tags": ["Clientes"], "parameters": [ { "in": "query", "name": "id", "schema": { "type": "integer" }, "description": "Filtrar por ID específico (opcional)" }, { "in": "query", "name": "nome", "schema": { "type": "string" }, "description": "Filtrar por nome (busca parcial com LIKE)" }, { "in": "query", "name": "url", "schema": { "type": "string" }, "description": "Filtrar por URL (busca parcial com LIKE)" }, { "in": "query", "name": "apis", "schema": { "type": "string" }, "description": "Filtrar por APIs habilitadas (busca parcial com LIKE)" }, { "in": "query", "name": "sort_by", "schema": { "type": "string", "default": "id" }, "description": "Campo para ordenação" }, { "in": "query", "name": "sort_direction", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "description": "Direção da ordenação" } ], "responses": { "200": { "description": "Lista de clientes com paginação", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Os clientes cadastrados são:" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "nome": { "type": "string" }, "url": { "type": "string" }, "apis": { "type": "string", "description": "APIs separadas por vírgula" }, "tier": { "type": "string", "enum": [ "free", "starter", "premium", "business", "enterprise" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "monthly_limits": { "type": "object", "properties": { "id": { "type": "integer" }, "id_cliente": { "type": "integer" }, "max_tokens_month": { "type": "integer" }, "max_summarization_tokens_month": { "type": "integer" }, "max_time_month": { "type": "integer", "description": "Horas de transcrição" }, "max_requests_per_time": { "type": "integer" } } } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer", "default": 15 }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" } } } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Cadastrar novo cliente (Admin)", "tags": ["Clientes"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["nome", "url", "apis", "tier"], "properties": { "nome": { "type": "string", "maxLength": 255, "description": "Nome do cliente" }, "url": { "type": "string", "format": "uri", "maxLength": 255, "description": "URL do cliente (deve ser válida)" }, "apis": { "type": "string", "maxLength": 255, "description": "APIs habilitadas separadas por vírgula (ex: transcriptions,completions)" }, "tier": { "type": "string", "enum": [ "free", "starter", "premium", "business", "enterprise" ], "maxLength": 30, "description": "Plano do cliente" }, "monthly_limits": { "type": "object", "description": "Limites customizados (obrigatório se tier=enterprise). Se não informado, usa defaults do config/app.php", "properties": { "max_tokens_month": { "type": "integer", "minimum": 0, "description": "Tokens de completions por mês" }, "max_summarization_tokens_month": { "type": "integer", "minimum": 0, "description": "Tokens de sumarização por mês" }, "max_time_month": { "type": "integer", "minimum": 0, "description": "Horas de transcrição por mês" }, "max_requests_per_time": { "type": "integer", "minimum": 0, "default": 60, "description": "Rate limit (requests por minuto)" } } } } } } } }, "responses": { "201": { "description": "Cliente cadastrado com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Cliente cadastrado." }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "nome": { "type": "string" }, "url": { "type": "string" }, "apis": { "type": "string" }, "tier": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "monthly_limit": { "type": "object" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Atualizar cliente existente (Admin)", "tags": ["Clientes"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id", "tier"], "properties": { "id": { "type": "integer", "description": "ID do cliente a ser atualizado" }, "nome": { "type": "string", "maxLength": 255 }, "url": { "type": "string", "format": "uri", "maxLength": 255 }, "apis": { "type": "string", "maxLength": 255 }, "tier": { "type": "string", "enum": [ "free", "starter", "premium", "business", "enterprise" ], "maxLength": 30 }, "monthly_limits": { "type": "object", "description": "Novos limites (obrigatório se tier=enterprise)", "properties": { "max_tokens_month": { "type": "integer", "minimum": 0 }, "max_summarization_tokens_month": { "type": "integer", "minimum": 0 }, "max_time_month": { "type": "integer", "minimum": 0 }, "max_requests_per_time": { "type": "integer", "minimum": 0 } } } } } } } }, "responses": { "200": { "description": "Cliente atualizado com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billings": { "get": { "summary": "Obter registros de billing com filtros (Admin)", "tags": ["Billings"], "parameters": [ { "in": "query", "name": "id", "schema": { "type": "integer" }, "description": "Filtrar por ID específico" }, { "in": "query", "name": "id_cliente", "schema": { "type": "integer" }, "description": "Filtrar por ID do cliente" }, { "in": "query", "name": "numero_requests", "schema": { "type": "integer" }, "description": "Número de requests" }, { "in": "query", "name": "api_utilizada", "schema": { "type": "string" }, "description": "API utilizada (transcriptions, completions, etc)" }, { "in": "query", "name": "status_code", "schema": { "type": "integer" }, "description": "HTTP status code" }, { "in": "query", "name": "id_token_used", "schema": { "type": "integer" }, "description": "ID do token utilizado" }, { "in": "query", "name": "modelo_utilizado", "schema": { "type": "string" }, "description": "Modelo IA utilizado" }, { "in": "query", "name": "data_ini", "schema": { "type": "string", "format": "date" }, "description": "Data inicial (YYYY-MM-DD)" }, { "in": "query", "name": "data_fim", "schema": { "type": "string", "format": "date" }, "description": "Data final (YYYY-MM-DD)" }, { "in": "query", "name": "hora_ini", "schema": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$", "default": "00:00" }, "description": "Hora inicial (HH:MM)" }, { "in": "query", "name": "hora_fim", "schema": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$", "default": "23:59" }, "description": "Hora final (HH:MM)" }, { "in": "query", "name": "sort_by", "schema": { "type": "string", "default": "created_at" }, "description": "Campo para ordenação" }, { "in": "query", "name": "sort_order", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" }, "description": "Ordem" }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 100, "maximum": 1000 }, "description": "Registros por página" } ], "responses": { "200": { "description": "Registros de billing com paginação", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "id_cliente": { "type": "integer" }, "nome_cliente": { "type": "string" }, "numero_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "segundos": { "type": "number", "description": "Tempo de transcrição em segundos" }, "caracteres": { "type": "integer" }, "api_utilizada": { "type": "string" }, "modelo_utilizado": { "type": "string" }, "status_code": { "type": "integer" }, "msg": { "type": "string" }, "id_token_used": { "type": "integer" }, "request_time": { "type": "number", "description": "Tempo de resposta em ms" }, "id_transcription": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "applied_filters": { "type": "object" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" } } } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Criar registro de billing manualmente (Admin)", "tags": ["Billings"], "description": "Normalmente criado automaticamente pelo sistema. Este endpoint permite criação manual.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id_cliente", "api_utilizada", "status_code", "id_token_used", "nome_cliente", "modelo_utilizado" ], "properties": { "id_cliente": { "type": "integer" }, "nome_cliente": { "type": "string" }, "api_utilizada": { "type": "string" }, "modelo_utilizado": { "type": "string" }, "status_code": { "type": "integer" }, "msg": { "type": "string" }, "id_token_used": { "type": "integer" }, "request_time": { "type": "number" }, "input_tokens": { "type": "integer", "default": 0 }, "output_tokens": { "type": "integer", "default": 0 }, "segundos": { "type": "number", "default": 0 }, "caracteres": { "type": "integer", "default": 0 }, "id_transcription": { "type": "string", "nullable": true } } } } } }, "responses": { "201": { "description": "Billing criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Atualizar registro de billing (Admin)", "tags": ["Billings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer", "description": "ID do billing" }, "id_cliente": { "type": "integer" }, "api_utilizada": { "type": "string" }, "modelo_utilizado": { "type": "string" }, "status_code": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "segundos": { "type": "number" }, "caracteres": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Billing atualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/criarToken": { "post": { "summary": "Criar token de acesso para cliente (Admin)", "tags": ["Tokens"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "ability", "name"], "properties": { "url": { "type": "string", "maxLength": 255, "description": "URL do cliente (usado para localizar o cliente)" }, "name": { "type": "string", "maxLength": 255, "description": "Nome descritivo do token" }, "ability": { "type": "string", "maxLength": 255, "description": "Permissão do token. Use '*' para admin (todas rotas) ou 'cliente' para um token para um cliente." }, "expiration": { "type": "integer", "maximum": 365, "default": -1, "description": "Dias até expiração. Use -1 para token sem expiração ou informe a quantidade de dias. Não precisa ser informado na request" } } } } } }, "responses": { "201": { "description": "Token criado com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Token criado:" }, "status": { "type": "integer", "example": 201 }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "Token plaintext (salve, não é recuperável)" }, "validade_token": { "type": "string", "description": "Data de validade ou 'forever'" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/alterarStatusToken": { "patch": { "summary": "Ativar/Inativar token (Admin)", "tags": ["Tokens"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id", "status"], "properties": { "id": { "type": "integer", "description": "ID do token" }, "status": { "type": "integer", "enum": [0, 1], "description": "Status do token: 0 = inativo, 1 = ativo" } } } } } }, "responses": { "200": { "description": "Status do token atualizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "O token foi atualizado com sucesso." }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "id_token": { "type": "integer" }, "id_cliente": { "type": "integer" }, "token_name": { "type": "string" }, "status": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/revogarToken": { "delete": { "summary": "Revogar (deletar) token de acesso (Admin)", "tags": ["Tokens"], "responses": { "200": { "description": "Token revogado com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "O token foi revogado com sucesso." }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "id_token": { "type": "integer" }, "id_cliente": { "type": "integer" }, "token_name": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "in": "query", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "ID do token na tabela personal_access_tokens" } ] } }, "/v1/clientes/{id}": { "delete": { "summary": "Deletar cliente (Admin)", "tags": ["Clientes"], "description": "IMPORTANTE: No Laravel, o ID é enviado no body. Documentado como path parameter para conformidade RESTful.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "ID do cliente (na prática, envie no body da request)" }, { "in": "query", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "ID do cliente a ser deletado" } ], "responses": { "200": { "description": "Cliente removido com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "O cliente de id 2 foi removido com sucesso." }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "description": "Dados do cliente deletado" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/billings/{id}": { "delete": { "summary": "Deletar registro de billing (Admin)", "tags": ["Billings"], "description": "IMPORTANTE: No Laravel, o ID é enviado no body. Documentado como path parameter para conformidade RESTful.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "ID do billing (na prática, envie no body da request)" }, { "in": "query", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "ID do billing a ser deletado" } ], "responses": { "200": { "description": "Billing deletado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object" } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models": { "get": { "summary": "Listar todos os modelos disponíveis", "tags": ["Models"], "responses": { "200": { "description": "Lista de todos os modelos IA disponíveis", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Modelos disponíveis" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "model": { "type": "string" }, "broker": { "type": "string" }, "multiplier": { "type": "number" }, "is_active": { "type": "boolean" } } } } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models/completions": { "get": { "summary": "Listar modelos para completions", "tags": ["Models"], "responses": { "200": { "description": "Modelos disponíveis para chat completions", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Modelos de completions disponíveis" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "gpt-4o", "gpt-4o-mini", "gemini-1.5-pro" ] } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models/agents": { "get": { "summary": "Listar modelos para agents", "tags": ["Models"], "description": "Retorna modelos de IA disponíveis para uso em agents com tool calling", "responses": { "200": { "description": "Modelos disponíveis para agents com suporte a tool calling", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Modelos de agents disponíveis" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "gpt-4o", "gpt-4o-mini", "gemini-1.5-pro", "claude-3-5-sonnet" ] } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models/transcriptions": { "get": { "summary": "Listar modelos para transcrições", "tags": ["Models"], "responses": { "200": { "description": "Modelos disponíveis para transcrições de áudio", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Modelos de transcrição disponíveis" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "whisper-1", "gemini-1.5-flash" ] } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models/summarizations": { "get": { "summary": "Listar modelos para sumarização", "tags": ["Models"], "responses": { "200": { "description": "Modelos disponíveis para sumarização", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Modelos de sumarização disponíveis" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "string" } } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/models/embeddings": { "get": { "summary": "Listar modelos para embeddings", "tags": ["Models"], "description": "Retorna modelos de IA disponíveis para geração de embeddings vetoriais", "responses": { "200": { "description": "Modelos disponíveis para geração de embeddings", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Modelos de embeddings disponíveis" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "string" }, "example": [ "text-embedding-3-small", "text-embedding-3-large", "text-embedding-ada-002" ] } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/knowledge/list": { "get": { "summary": "Listar Knowledge Bases com filtros", "operationId": "listKnowledgeBases", "tags": ["Knowledge Bases"], "parameters": [ { "name": "page", "in": "query", "description": "Número da página", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Itens por página", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 15 } }, { "name": "display_name", "in": "query", "description": "Filtro por nome (busca parcial)", "schema": { "type": "string" } }, { "name": "description", "in": "query", "description": "Filtro por descrição (busca parcial)", "schema": { "type": "string" } }, { "name": "kb_identifier", "in": "query", "description": "Filtro por identificador único", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filtro por status", "schema": { "type": "boolean" } }, { "name": "max_documents", "in": "query", "description": "KBs com até X documentos", "schema": { "type": "integer", "minimum": 0 } }, { "name": "max_chunks", "in": "query", "description": "KBs com até X chunks", "schema": { "type": "integer", "minimum": 0 } }, { "name": "sort_by", "in": "query", "description": "Campo para ordenação", "schema": { "type": "string", "enum": [ "created_at", "display_name", "document_count", "total_chunks" ], "default": "created_at" } }, { "name": "sort_direction", "in": "query", "description": "Direção da ordenação", "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" } } ], "responses": { "200": { "description": "Lista de Knowledge Bases paginada", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Bases de conhecimento" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { } }, "success": { "type": "boolean", "example": true }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "example": 25 }, "per_page": { "type": "integer", "example": 15 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 2 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 15 } } } } } } } } } } }, "/v1/knowledge/list/{id}": { "get": { "summary": "Detalhes de uma Knowledge Base específica", "operationId": "findKnowledgeBase", "tags": ["Knowledge Bases"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da Knowledge Base", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Página de chunks", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Chunks por página", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Detalhes da KB com seus chunks", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Chunks da base de conhecimento 'Contratos 2024'" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } }, "documents": { "type": "array", "items": { "type": "string" } }, "metadatas": { "type": "array", "items": { "type": "object" } } } }, "pagination": { "type": "object" } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/knowledge/create": { "post": { "summary": "Criar nova Knowledge Base", "operationId": "createKnowledgeBase", "tags": ["Knowledge Bases"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["display_name"], "properties": { "display_name": { "type": "string", "maxLength": 255, "example": "Contratos Comerciais 2024", "description": "Nome amigável da Knowledge Base" }, "description": { "type": "string", "maxLength": 2000, "example": "Base contendo todos os contratos comerciais do ano de 2024", "description": "Descrição detalhada (opcional)" } } } } } }, "responses": { "201": { "description": "Knowledge Base criada com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Base de conhecimento criada" }, "status": { "type": "integer", "example": 201 }, "data": { } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" } } } }, "/v1/knowledge/documents": { "post": { "summary": "Enviar documentos ou texto para Knowledge Base", "description": "Upload de arquivos ou texto puro para processamento e vetorização em uma Knowledge Base. Os documentos são processados de forma assíncrona via jobs. Cada arquivo é processado individualmente e gera chunks com metadados únicos (document_name, document_id, file_hash, etc). Use GET /v1/documents/jobs/{job_id} para acompanhar o progresso.", "operationId": "uploadDocumentsToKnowledgeBase", "tags": ["Knowledge Bases", "Documents"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["kb_id"], "properties": { "kb_id": { "type": "integer", "description": "ID da Knowledge Base (deve pertencer ao cliente autenticado)", "example": 5 }, "files": { "type": "array", "description": "Array de arquivos para upload (máximo 10 arquivos). Não pode ser enviado junto com 'text'.", "maxItems": 10, "items": { "type": "string", "format": "binary" } }, "text": { "type": "string", "description": "Texto puro para processar (máximo 100.000 caracteres). Não pode ser enviado junto com 'files'.", "maxLength": 100000, "example": "Este é um texto de exemplo que será dividido em chunks e vetorizado." }, "chunk_size": { "type": "integer", "description": "Tamanho de cada chunk em caracteres", "minimum": 100, "maximum": 3000, "default": 1000, "example": 1000 }, "overlap": { "type": "integer", "description": "Sobreposição entre chunks em caracteres (para manter contexto)", "minimum": 0, "maximum": 500, "default": 200, "example": 200 }, "provider": { "type": "string", "description": "Provider de parsing de documentos", "enum": ["docling", "unstructured"], "default": "docling", "example": "docling" } } }, "encoding": { "files": { "contentType": "application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, text/plain, text/markdown, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.openxmlformats-officedocument.presentationml.presentation" } } }, "application/json": { "schema": { "type": "object", "required": ["kb_id", "text"], "properties": { "kb_id": { "type": "integer", "example": 5 }, "text": { "type": "string", "maxLength": 100000, "example": "Este é um texto de exemplo que será dividido em chunks e vetorizado." }, "chunk_size": { "type": "integer", "minimum": 100, "maximum": 3000, "default": 1000 }, "overlap": { "type": "integer", "minimum": 0, "maximum": 500, "default": 200 } } } } } }, "responses": { "202": { "description": "Documentos/texto enfileirados para processamento assíncrono", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Arquivos enviados para processamento" }, "status": { "type": "integer", "example": 202 }, "data": { "type": "object", "properties": { "job_id": { "type": "string", "description": "ID do job para acompanhamento via GET /v1/documents/jobs/{job_id}", "example": "123" }, "kb_identifier": { "type": "string", "description": "Identificador único da Knowledge Base (formato: {id_cliente}_{nome}_{random})", "example": "1_contratos_tM4fgTd9QW46" }, "status": { "type": "string", "enum": ["queued"], "example": "queued" }, "input_type": { "type": "string", "enum": ["files", "text"], "description": "Tipo de entrada processada", "example": "files" } } }, "success": { "type": "boolean", "example": true } } }, "examples": { "multipleFiles": { "summary": "Upload de múltiplos arquivos", "value": { "msg": "Arquivos enviados para processamento", "status": 202, "data": { "job_id": "456", "kb_identifier": "1_contratos2024_AXOKtpXaSMWP", "status": "queued", "input_type": "files" }, "success": true } }, "textInput": { "summary": "Envio de texto puro", "value": { "msg": "Texto enviado para processamento", "status": 202, "data": { "job_id": "457", "status": "queued", "collection_name": "kb_cliente_1", "input_type": "text" }, "success": true } } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Não é permitido enviar arquivos e texto simultaneamente" }, "status": { "type": "integer", "example": 400 }, "data": { "type": "array", "example": [] } } } } } }, "404": { "description": "Knowledge Base não encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "A base de conhecimento informada não existe" }, "status": { "type": "integer", "example": 404 }, "data": { "type": "array", "example": [] } } } } } }, "422": { "description": "Erros de validação", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Erro de validação" }, "status": { "type": "integer", "example": 422 }, "data": { "type": "object", "properties": { "errors": { "type": "object", "example": { "files.0": [ "The files.0 failed to upload." ], "files.1": [ "Formatos aceitos: TXT, PDF, DOCX, DOC, MD, XLSX, XLS, PPTX" ], "files": [ "Máximo de 10 arquivos por requisição" ], "text": [ "Texto não pode exceder 100.000 caracteres" ], "chunk_size": [ "Chunk size deve estar entre 100 e 3000" ], "overlap": [ "Overlap deve estar entre 0 e 500" ] } } } } } } } } } } } }, "/v1/knowledge/update": { "put": { "summary": "Atualizar Knowledge Base", "operationId": "updateKnowledgeBase", "tags": ["Knowledge Bases"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer", "example": 5, "description": "ID da Knowledge Base" }, "display_name": { "type": "string", "maxLength": 255, "example": "Contratos Atualizados 2024" }, "description": { "type": "string", "maxLength": 2000, "example": "Descrição atualizada" }, "is_active": { "type": "boolean", "example": true, "description": "Status ativo/inativo" } } } } } }, "responses": { "200": { "description": "Knowledge Base atualizada", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Base atualizada" }, "status": { "type": "integer", "example": 200 } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/knowledge/delete/{id}": { "delete": { "summary": "Deletar Knowledge Base e seus chunks", "operationId": "deleteKnowledgeBase", "tags": ["Knowledge Bases"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da Knowledge Base", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Knowledge Base deletada com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Base processada" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "deleted_count": { "type": "integer", "example": 156 } } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/knowledge/{id}/chunks": { "post": { "summary": "Buscar chunks de uma KB com filtros de metadata", "operationId": "searchKnowledgeBaseChunks", "tags": ["Knowledge Bases"], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da Knowledge Base", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "document_type": { "type": "string", "example": ".pdf", "description": "Filtrar por tipo de documento" }, "document_name": { "type": "string", "example": "contrato-aluguel.pdf", "description": "Filtrar por nome do documento" }, "document_id": { "type": "string", "description": "UUID do documento" }, "file_hash": { "type": "string", "description": "Hash SHA256 do arquivo" }, "char_count_min": { "type": "integer", "minimum": 0, "example": 500, "description": "Mínimo de caracteres no chunk" }, "char_count_max": { "type": "integer", "minimum": 0, "example": 2000, "description": "Máximo de caracteres no chunk" }, "chunk_index": { "type": "integer", "minimum": 0, "description": "Índice específico do chunk" }, "total_chunks_min": { "type": "integer", "minimum": 0, "description": "Documentos com mínimo de chunks" }, "total_chunks_max": { "type": "integer", "minimum": 0, "description": "Documentos com máximo de chunks" }, "created_at_from": { "type": "string", "format": "date", "example": "2025-10-01", "description": "Data de criação a partir de (YYYY-MM-DD)" }, "created_at_to": { "type": "string", "format": "date", "example": "2025-10-31", "description": "Data de criação até (YYYY-MM-DD)" }, "page": { "type": "integer", "minimum": 1, "default": 1 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } } }, "examples": { "simple": { "summary": "Filtro simples por tipo", "value": { "document_type": ".pdf", "page": 1, "per_page": 20 } }, "complex": { "summary": "Filtros complexos combinados", "value": { "document_type": ".pdf", "char_count_min": 500, "char_count_max": 2000, "created_at_from": "2025-10-01", "created_at_to": "2025-10-31", "page": 1, "per_page": 50 } } } } } }, "responses": { "200": { "description": "Chunks filtrados com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Chunks filtrados com sucesso" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "collection_name": { "type": "string" }, "database_name": { "type": "string" }, "total_chunks": { "type": "integer", "example": 150 }, "has_filters": { "type": "boolean", "example": true }, "chunks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "document": { "type": "string" }, "metadata": { "type": "object", "properties": { "char_count": { "type": "integer" }, "chunk_index": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "document_id": { "type": "string" }, "document_name": { "type": "string" }, "document_type": { "type": "string" }, "file_hash": { "type": "string" }, "kb_identifier": { "type": "string" }, "total_chunks": { "type": "integer" } } } } } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" } } } } } } } } } } }, "/v1/chromadb/list": { "get": { "summary": "Listar databases ChromaDB (Admin)", "tags": ["ChromaDB - Databases (Admin)"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista de databases", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "string" } } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/chromadb/list/{name}": { "get": { "summary": "Obter database específico (Admin)", "tags": ["ChromaDB - Databases (Admin)"], "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "Nome do database" } ], "responses": { "200": { "description": "Detalhes do database", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object" } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/chromadb/create": { "post": { "summary": "Criar database ChromaDB (Admin)", "tags": ["ChromaDB - Databases (Admin)"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Nome do database" } } } } } }, "responses": { "201": { "description": "Database criado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 201 } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/chromadb/delete/{name}": { "delete": { "summary": "Deletar database ChromaDB (Admin)", "tags": ["ChromaDB - Databases (Admin)"], "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" }, "description": "Nome do database" } ], "responses": { "200": { "description": "Database deletado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 } } } } } }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/embeddings/create": { "post": { "summary": "Criar embeddings para textos", "tags": ["Embeddings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["input", "model"], "properties": { "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Texto ou array de textos para gerar embeddings" }, "model": { "type": "string", "description": "Modelo de embedding" } } } } } }, "responses": { "200": { "description": "Embeddings gerados", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "object", "properties": { "embedding": { "type": "array", "items": { "type": "number" } }, "index": { "type": "integer" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/embeddings/query": { "post": { "summary": "Query em collection com similaridade", "tags": ["Embeddings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["collection_name", "query_text"], "properties": { "collection_name": { "type": "string" }, "query_text": { "type": "string" }, "n_results": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } } } } }, "responses": { "200": { "description": "Resultados da query", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "object", "properties": { "document": { "type": "string" }, "metadata": { "type": "object" }, "distance": { "type": "number" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/embeddings/createEmbeddings": { "post": { "summary": "Criar e persistir embeddings em collection", "tags": ["Embeddings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["collection_name", "documents"], "properties": { "collection_name": { "type": "string" }, "documents": { "type": "array", "items": { "type": "string" } }, "metadatas": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "201": { "description": "Embeddings criados e persistidos", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 201 } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/embeddings/update": { "put": { "summary": "Atualizar embeddings existentes", "tags": ["Embeddings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collection_name", "ids", "documents" ], "properties": { "collection_name": { "type": "string" }, "ids": { "type": "array", "items": { "type": "string" } }, "documents": { "type": "array", "items": { "type": "string" } }, "metadatas": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Embeddings atualizados", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/embeddings/delete": { "delete": { "summary": "Deletar embeddings específicos", "tags": ["Embeddings"], "responses": { "200": { "description": "Embeddings deletados", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 } } } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "500": { "$ref": "#/components/responses/ServerError" } }, "parameters": [ { "in": "query", "name": "collection_name", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "ids", "required": true, "schema": { "type": "array" } } ] } }, "/v1/documents/jobs": { "get": { "summary": "Listar jobs de processamento de documentos", "tags": ["Documents"], "responses": { "200": { "description": "Lista de jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": "string" } } } } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/documents/jobs/{id}": { "get": { "summary": "Obter detalhes de job específico", "tags": ["Documents"], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "ID do job" } ], "responses": { "200": { "description": "Detalhes do job", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "result": { "type": "object" } } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/clientStats": { "get": { "summary": "Obter estatísticas do cliente autenticado", "tags": ["Estatísticas de consumo"], "parameters": [ { "in": "query", "name": "data_ini", "schema": { "type": "string", "format": "date" }, "description": "Data inicial (YYYY-MM-DD)" }, { "in": "query", "name": "data_fim", "schema": { "type": "string", "format": "date" }, "description": "Data final (YYYY-MM-DD)" } ], "responses": { "200": { "description": "Estatísticas do cliente autenticado com detalhamento de uso por tipo de API e limites mensais", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Stats de uso:" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "properties": { "id_cliente": { "type": "integer", "description": "ID do cliente", "example": 1 }, "tier": { "type": "string", "description": "Tier do cliente (free, starter, premium, business, enterprise)", "example": "premium" }, "nome_cliente": { "type": "string", "description": "Nome do cliente", "example": "Convert Company" }, "total_requests": { "type": "integer", "description": "Total de requisições realizadas no período", "example": 1250 }, "total_hours_used": { "type": "number", "description": "Total de horas utilizadas (transcriptions)", "example": 3.45 }, "total_transcriptions": { "type": "integer", "description": "Número de transcrições realizadas", "example": 150 }, "total_completions": { "type": "integer", "description": "Número de completions realizadas", "example": 800 }, "completion_tokens_used": { "type": "integer", "description": "Tokens utilizados em completions (input + output)", "example": 458900 }, "total_summarizations": { "type": "integer", "description": "Número de sumarizações realizadas", "example": 120 }, "summarization_tokens_used": { "type": "integer", "description": "Tokens utilizados em sumarizações", "example": 75000 }, "remaining_completion_tokens": { "type": "integer", "description": "Tokens restantes para completions no período", "example": 1541100 }, "remaining_summarization_tokens": { "type": "integer", "description": "Tokens restantes para sumarizações no período", "example": 425000 }, "remaining_hours": { "type": "number", "description": "Horas restantes para transcriptions", "example": 46.55 }, "agents": { "type": "object", "description": "Estatísticas de uso de agents com tool calling", "properties": { "total_agents_completions": { "type": "integer", "description": "Número de agent completions realizadas", "example": 180 }, "agents_completion_tokens_used": { "type": "integer", "description": "Tokens utilizados em agent completions", "example": 95000 }, "agents_credits": { "type": "integer", "description": "Total de créditos disponíveis para agents no mês", "example": 100000 }, "agents_credit_spent": { "type": "integer", "description": "Créditos gastos em agents (agregados por response_id)", "example": 12500 }, "remaining_agent_credits": { "type": "integer", "description": "Créditos restantes para agents", "example": 87500 }, "reserve_credits": { "type": "integer", "description": "Total de créditos na reserva", "example": 50000 }, "reserve_credits_used": { "type": "integer", "description": "Créditos de reserva utilizados", "example": 2000 }, "remaining_reserve_credits": { "type": "integer", "description": "Créditos de reserva restantes", "example": 48000 } } }, "data_ini": { "type": "string", "format": "date", "description": "Data inicial do filtro aplicado", "example": "2024-01-01", "nullable": true }, "data_fim": { "type": "string", "format": "date", "description": "Data final do filtro aplicado", "example": "2024-01-31", "nullable": true } } } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum" } }, "responses": { "ForbiddenError": { "description": "Usuário está autenticado mas não possuí permissões para acessar a rota", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Usuário não tem permissões para ação" }, "status": { "type": "integer", "example": 403 }, "data": { "type": "array", "items": {}, "default": [] } } } } } }, "BadRequestError": { "description": "Inconsistências na entrada/Erro na Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Foram encontradas inconsistências na entrada. Verifique os dados e tente novamente." }, "status": { "type": "integer", "example": 400 }, "data": { "type": "array", "items": {}, "default": [] } } } } } }, "NotFoundError": { "description": "Nenhum registro encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Nenhum registro encontrado" }, "status": { "type": "integer", "example": 404 }, "data": { "type": "array", "items": {}, "default": [] } } } } } }, "ServerError": { "description": "Erro no servidor", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Erro interno no servidor." }, "status": { "type": "integer", "example": 500 }, "data": { "type": "array", "items": {}, "default": [] } } } } } }, "UnauthorizedError": { "description": "Usuário não autorizado", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Usuário não autorizado" }, "status": { "type": "integer", "example": 401 }, "data": { "type": "array", "items": {}, "default": [] } } } } } }, "RateLimitError": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Limite de requisições excedido. Tente novamente mais tarde." }, "status": { "type": "integer", "example": 429 }, "data": { "type": "object", "properties": { "retry_after": { "type": "integer", "description": "Tempo em segundos para tentar novamente" } } } } } } } } } } }