API semântica e MCP
Conecte agentes de IA autorizados às evidências da Blocchi sem compartilhar credenciais das fontes.
API semântica e MCP
A Blocchi oferece a API governada em /api/v1, documentada em /api/openapi/v1, e um gateway MCP em /api/mcp. O agente utiliza sua identidade autorizada na Blocchi, sem receber segredos dos conectores.
Leituras disponíveis
GET /api/v1/data-plus/semantic-catalog: entidades semânticas por dataset, frescor da sincronização e metadados de mapeamentos salvos. Filtros:connectionId,page(1–100),limit(1–50).GET /api/v1/business-graph: relacionamentos paginados com origem e escopo de vendedor/unidade aplicado no servidor.GET /api/v1/business-graph/types: tipos de relacionamentos.GET /api/v1/data-plus/quality: qualidade, status das fontes e sugestões permitidas.GET /api/v1/findingseGET /api/v1/findings/{id}/evidence: achados e evidências.
No MCP, use blocchi.list_semantic_catalog, blocchi.list_business_graph, blocchi.list_business_graph_relationship_types, blocchi.get_data_quality e blocchi.get_finding_evidence.
Prévia sem alteração
POST /api/v1/data-plus/mapping-preview ou blocchi.preview_semantic_mapping aceita connectionId e até 50 vínculos com entityInstanceId, semanticAttributeId e sourceField. A resposta verifica a estrutura e possíveis conflitos, mas nunca aplica, publica ou aprova um mapeamento. Não valida a coluna na origem nem atribui confiança de IA.
Segurança e limites
É preciso ter headless:read, permissão Data+ e autorização para o tenant. O catálogo semântico recusa leituras quando o usuário tem escopo restrito por vendedor/unidade; o Grafo de Negócios aplica filtros nos próprios registros. Fontes com leitura Data+ desabilitada não aparecem. Fontes com autorização delegada por usuário permanecem excluídas até haver verificação das permissões nativas. Nenhuma credencial da origem é retornada.
Mapeamentos salvos aparecem como saved_unverified e não significam aprovação. As APIs governadas de X-Ray, propostas de mapeamento, perfil de Cleanup Studio e preview agregado de limpeza estão disponíveis; o catálogo continua identificando configurações salvas como saved_unverified. Os novos endpoints não executam limpeza, mastering, merge, ativação nem publicação remota.
A política de quotas, limitação de chamadas e telemetria existente também se aplica ao REST/MCP. Analise a origem e a atualização das evidências e trate resultados indisponíveis explicitamente.
APIs de diagnóstico e governança
A partir da integração dos serviços Data+, use GET /api/v1/data-plus/semantic-mapping?connectionId=<uuid>&datasetId=<uuid> para proposta não publicada, GET /api/v1/data-plus/business-xray para diagnóstico e GET /api/v1/data-plus/cleanup-profile (apenas gestor humano autorizado) para metadados das receitas. Os previews que contêm valores de linhas e decisões de aprovação/publicação continuam restritos à experiência de stewardship autenticada.
Simulação agregada de limpeza
POST /api/v1/data-plus/cleanup-preview reutiliza o simulador do Cleanup Studio, retornando somente contagens de uma amostra de até 500 registros armazenados. Exemplo: { "datasetId": "<uuid>", "rules": [{ "field": "name", "kind": "trim" }] }. A ferramenta MCP correspondente é blocchi.preview_cleanup_recipe. O acesso exige usuário humano administrador/gestor, Data+ Stewardship e permissão para ler a fonte. Fontes delegadas são excluídas; valores originais, resultados por registro, mapas de enum e tokens de aprovação/publicação nunca são retornados. Uma simulação não aplica alterações. As regras rodam em ordem, até 100, e aceitam as mesmas opções do Cleanup Studio, exceto enum_map, que fica no studio.