{"openapi":"3.1.0","info":{"title":"Opiagile RAG Core API","description":"API HTTP para integrar aplicações, portais, gateways e automações ao core RAG da Opiagile.\n\nUse esta documentação para validar ingestão de documentos, chat com fontes,\nworkspaces, observabilidade e handoff. Endpoints protegidos exigem o header\n`X-OPIAGILE-API-KEY`.\n","contact":{"name":"Opiagile","url":"https://opiagile.com","email":"contato@opiagile.com"},"license":{"name":"MIT","url":"https://github.com/opiagile/opiagile-ai-rag-core/blob/main/LICENSE"},"version":"v0.11"},"servers":[{"url":"https://opiagile.com","description":"Ambiente de demonstração controlada"}],"security":[{"OpiagileApiKey":[]}],"tags":[{"name":"handoff-controller","description":"Encaminhamento para atendimento humano."},{"name":"external-tool-controller","description":"Ferramentas controladas por workspace."},{"name":"observability-controller","description":"Trace de recuperação, fontes e resposta."},{"name":"provider-controller","description":"Status seguro de provedores IA e fallback."},{"name":"document-controller","description":"Ingestão e consulta de documentos por workspace."},{"name":"feedback-controller","description":"Feedback de qualidade sobre respostas do RAG."},{"name":"conversation-controller","description":"Histórico e conversas para auditoria operacional."},{"name":"chat-controller","description":"Chat RAG com fontes, memória e LLM opcional."},{"name":"version-controller","description":"Metadados públicos da aplicação."},{"name":"workspace-controller","description":"Workspaces disponíveis para uma chave ou tenant."}],"paths":{"/api/tools/{slug}/sql/query":{"post":{"tags":["external-tool-controller"],"operationId":"executeSql","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlToolExecutionRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/SqlToolExecutionResponse"}}}}}}},"/api/feedback":{"post":{"tags":["feedback-controller"],"operationId":"register","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}}}}},"/api/documents/upload":{"post":{"tags":["document-controller"],"operationId":"upload","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DocumentUploadResponse"}}}}}}},"/api/chat":{"post":{"tags":["chat-controller"],"operationId":"chat","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}}}}},"/api/handoffs/{id}/status":{"patch":{"tags":["handoff-controller"],"operationId":"updateStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateHandoffStatusRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HandoffResponse"}}}}}}},"/api/workspaces":{"get":{"tags":["workspace-controller"],"operationId":"findWorkspaces","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceResponse"}}}}}}}},"/api/version":{"get":{"tags":["version-controller"],"operationId":"version","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/VersionResponse"}}}}}}},"/api/tools":{"get":{"tags":["external-tool-controller"],"operationId":"list","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalToolResponse"}}}}}}}},"/api/providers/status":{"get":{"tags":["provider-controller"],"summary":"Consulta status seguro de LLM, embeddings, recuperação e planner","operationId":"status","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ProviderStatusResponse"}}}}}}},"/api/observability/conversations/{id}/trace":{"get":{"tags":["observability-controller"],"operationId":"trace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationTraceResponse"}}}}}}},"/api/handoffs":{"get":{"tags":["handoff-controller"],"operationId":"findAll","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HandoffResponse"}}}}}}}},"/api/handoffs/{id}":{"get":{"tags":["handoff-controller"],"operationId":"findById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/HandoffResponse"}}}}}}},"/api/documents":{"get":{"tags":["document-controller"],"operationId":"findAll_1","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryResponse"}}}}}}}},"/api/documents/{id}":{"get":{"tags":["document-controller"],"operationId":"findById_1","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DocumentDetailResponse"}}}}}}},"/api/documents/{id}/chunks":{"get":{"tags":["document-controller"],"operationId":"findChunks","parameters":[{"name":"X-Tenant-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Workspace-Id","in":"header","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentChunkResponse"}}}}}}}},"/api/conversations/{id}/summary":{"get":{"tags":["conversation-controller"],"operationId":"summarize","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationSummaryResponse"}}}}}}},"/api/conversations/{id}/messages":{"get":{"tags":["conversation-controller"],"operationId":"findMessages","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MessageResponse"}}}}}}}}},"components":{"schemas":{"SqlToolExecutionRequest":{"type":"object","properties":{"sql":{"type":"string","maxLength":4000,"minLength":0},"maxRows":{"type":"integer","format":"int32","maximum":100,"minimum":1}},"required":["sql"]},"SqlToolExecutionResponse":{"type":"object","properties":{"toolSlug":{"type":"string"},"rowCount":{"type":"integer","format":"int32"},"truncated":{"type":"boolean"},"latencyMs":{"type":"integer","format":"int32"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","additionalProperties":{}}}}},"FeedbackRequest":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"rating":{"type":"string","enum":["POSITIVE","NEGATIVE"]},"reason":{"type":"string","maxLength":500,"minLength":0}},"required":["conversationId","rating"]},"FeedbackResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"rating":{"type":"string","enum":["POSITIVE","NEGATIVE"]},"reason":{"type":"string"},"tenant":{"type":"string"},"workspace":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"DocumentUploadResponse":{"type":"object","properties":{"documentId":{"type":"string","format":"uuid"},"tenantId":{"type":"string"},"workspaceId":{"type":"string"},"filename":{"type":"string"},"status":{"type":"string"},"chunkCount":{"type":"integer","format":"int32"},"embeddingProvider":{"type":"string"}}},"ChatRequest":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"},"message":{"type":"string","maxLength":1200,"minLength":0},"channel":{"type":"string","maxLength":32,"minLength":0},"contactId":{"type":"string","maxLength":128,"minLength":0},"responseLanguage":{"type":"string","pattern":"(?i)^(EN|ENGLISH|ES|SPANISH|PT|PORTUGUESE|PORTUGUES)$"}},"required":["message"]},"ChatResponse":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"},"answer":{"type":"string"},"intent":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ChatSourceResponse"}},"handoffRequired":{"type":"boolean"},"leadStatus":{"type":"string"},"latencyMs":{"type":"integer","format":"int64"},"responseMode":{"type":"string"},"llmProvider":{"type":"string"},"model":{"type":"string"},"fallbackReason":{"type":"string"},"llmLatencyMs":{"type":"integer","format":"int64"},"promptTokens":{"type":"integer","format":"int32"},"completionTokens":{"type":"integer","format":"int32"},"totalTokens":{"type":"integer","format":"int32"}}},"ChatSourceResponse":{"type":"object","properties":{"documentId":{"type":"string","format":"uuid"},"filename":{"type":"string"},"chunkId":{"type":"string","format":"uuid"},"score":{"type":"number","format":"double"},"excerpt":{"type":"string"}}},"UpdateHandoffStatusRequest":{"type":"object","properties":{"status":{"type":"string","minLength":1}},"required":["status"]},"HandoffResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"reason":{"type":"string"},"summary":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"WorkspaceResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantSlug":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}},"VersionResponse":{"type":"object","properties":{"appName":{"type":"string"},"version":{"type":"string"},"environment":{"type":"string"},"javaVersion":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"ExternalToolResponse":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"description":{"type":"string"},"allowedTables":{"type":"array","items":{"type":"string"}},"defaultLimit":{"type":"integer","format":"int32"},"maxLimit":{"type":"integer","format":"int32"}}},"ChatProviderStatusResponse":{"type":"object","properties":{"requestedResponseMode":{"type":"string"},"requestedProvider":{"type":"string"},"activeProvider":{"type":"string"},"model":{"type":"string"},"openAiApiKeyConfigured":{"type":"boolean"},"fallbackEnabled":{"type":"boolean"},"fallbackProvider":{"type":"string"},"status":{"type":"string"}}},"EmbeddingProviderStatusResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"activeProvider":{"type":"string"},"model":{"type":"string"},"dimensions":{"type":"integer","format":"int32"},"openAiApiKeyConfigured":{"type":"boolean"},"fallbackEnabled":{"type":"boolean"},"fallbackProvider":{"type":"string"},"status":{"type":"string"}}},"ProviderStatusResponse":{"type":"object","properties":{"status":{"type":"string"},"chat":{"$ref":"#/components/schemas/ChatProviderStatusResponse"},"embeddings":{"$ref":"#/components/schemas/EmbeddingProviderStatusResponse"},"retrieval":{"$ref":"#/components/schemas/RetrievalProviderStatusResponse"},"toolPlanner":{"$ref":"#/components/schemas/ToolPlannerProviderStatusResponse"},"warnings":{"type":"array","items":{"type":"string"}}}},"RetrievalProviderStatusResponse":{"type":"object","properties":{"activeStrategy":{"type":"string"},"pgvectorReadyByConfiguration":{"type":"boolean"},"fallbackEnabled":{"type":"boolean"},"fallbackProvider":{"type":"string"},"status":{"type":"string"}}},"ToolPlannerProviderStatusResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"activeProvider":{"type":"string"},"openAiApiKeyConfigured":{"type":"boolean"},"status":{"type":"string"}}},"ConversationTraceResponse":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/MessageResponse"}},"retrievals":{"type":"array","items":{"$ref":"#/components/schemas/RetrievalTraceResponse"}},"handoffs":{"type":"array","items":{"$ref":"#/components/schemas/HandoffResponse"}}}},"MessageResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"role":{"type":"string"},"content":{"type":"string"},"intent":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"RetrievalTraceResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"query":{"type":"string"},"retrievedChunks":{"type":"string"},"latencyMs":{"type":"integer","format":"int32"},"intent":{"type":"string"},"handoffRequired":{"type":"boolean"},"fallbackReason":{"type":"string"},"provider":{"type":"string"},"responseMode":{"type":"string"},"llmProvider":{"type":"string"},"model":{"type":"string"},"llmLatencyMs":{"type":"integer","format":"int32"},"promptTokens":{"type":"integer","format":"int32"},"completionTokens":{"type":"integer","format":"int32"},"totalTokens":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"}}},"DocumentSummaryResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string"},"workspaceId":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"sourceType":{"type":"string"},"status":{"type":"string"},"chunkCount":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"}}},"DocumentDetailResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string"},"workspaceId":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"sourceType":{"type":"string"},"status":{"type":"string"},"chunkCount":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"}}},"DocumentChunkResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"documentId":{"type":"string","format":"uuid"},"chunkIndex":{"type":"integer","format":"int32"},"content":{"type":"string"},"metadata":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"ConversationSummaryResponse":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"},"summary":{"type":"string"}}}},"securitySchemes":{"OpiagileApiKey":{"type":"apiKey","description":"API key tenant-aware fornecida pela Opiagile para apps, gateways e integrações.","name":"X-OPIAGILE-API-KEY","in":"header"}}}}