Referência da API
O Canopy expõe uma API REST completa que alimenta tudo o que pode fazer na interface web. Pode utilizá-la para automatizar atualizações de inventário, integrar com pipelines CI/CD, criar dashboards personalizados ou extrair dados de AE para outras ferramentas (BI, GRC, ITSM, folhas de cálculo).
A especificação OpenAPI 3.1 completa está disponível na secção Endpoints de API da barra lateral — cada endpoint, parâmetro e forma de resposta, regenerada a partir do código-fonte do backend em cada versão.
URL Base
Todos os endpoints da API estão sob o prefixo /api/v1. O URL do seu ambiente Canopy segue o padrão:
https://{o-seu-slug}-canopy.rhizo-tech.org/api/v1
Substitua {o-seu-slug} pelo slug da sua organização, que aparece na sua conta Rhizo e no URL que usa para aceder ao Canopy.
A única exceção é o endpoint de estado de saúde, que está montado em /api/health (sem prefixo de versão).
Referência API Interativa
A especificação OpenAPI 3.1 completa está disponível na secção Endpoints de API da barra lateral. Cada página de endpoint inclui um playground interativo onde pode introduzir o seu bearer token e executar pedidos em directo contra o seu ambiente Canopy.
A especificação em bruto também está disponível para descarga para geradores de código:
https://docs.rhizo-tech.org/api/openapi.json
Para utilizar o playground interativo, abra qualquer página de endpoint na secção Endpoints de API da barra lateral, introduza o seu bearer token no campo Authorization, preencha os parâmetros e clique em Send.
Autenticação
Todos os endpoints exceto /auth/*, a verificação de estado de saúde e os portais web públicos requerem um JSON Web Token enviado no cabeçalho Authorization:
Authorization: Bearer <access_token>
Obter um token
POST /api/v1/auth/login com o seu email e palavra-passe:
curl -X POST https://{o-seu-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
-H "Content-Type: application/json" \
A resposta contém um access_token:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer"
}
Os tokens são válidos por 24 horas. Utilize POST /api/v1/auth/refresh para prolongar uma sessão sem voltar a introduzir credenciais.
Se a sua organização utiliza Single Sign-On, não pode iniciar sessão com email/palavra-passe via API. Peça ao seu administrador Canopy para criar uma conta de serviço dedicada com uma palavra-passe local para automação.
Usar o token
curl https://{o-seu-slug}-canopy.rhizo-tech.org/api/v1/cards \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Permissões
A API aplica as mesmas regras RBAC que a interface web. Cada endpoint de mutação verifica tanto a função ao nível da aplicação do chamador como quaisquer funções de partes interessadas que detém no cartão afetado. Não existem "permissões de API" separadas nem contornos para contas de serviço — os scripts de automação funcionam com as permissões do utilizador cujo token utilizam.
Se um pedido falhar com 403 Forbidden, o token é válido mas o utilizador não tem a permissão necessária. Consulte a página Utilizadores e Funções para o registo de permissões.
Grupos de Endpoints Comuns
A referência na barra lateral é a fonte completa de verdade; a tabela abaixo é um mapa rápido dos grupos mais utilizados:
| Prefixo | Finalidade |
|---|---|
/auth | Início de sessão, registo, callback SSO, renovação de token, informações do utilizador atual |
/cards | CRUD de cartões (a entidade central), hierarquia, histórico, aprovação, exportação CSV |
/relations | CRUD de relações entre cartões |
/metamodel | Tipos de cartão, campos, secções, subtipos, tipos de relação |
/reports | KPIs do dashboard, portefólio, matriz, ciclo de vida, dependências, custo, qualidade de dados |
/bpm | Gestão de Processos de Negócio — diagramas, elementos, versões de fluxo, avaliações |
/ppm | Gestão de Portefólio de Projetos — iniciativas, relatórios de estado, WBS, tarefas, custos, riscos |
/turbolens | Análise com IA (fornecedores, duplicados, arquitetura AI) |
/risks | Registo de Riscos de AE (TOGAF Fase G) |
/diagrams | Diagramas DrawIO |
/soaw | Documentos de Declaração de Trabalho de Arquitetura |
/adr | Registos de Decisão de Arquitetura |
/users, /roles | Administração de utilizadores e funções (apenas admin) |
/settings | Configurações da aplicação (logótipo, moeda, SMTP, IA, ativação de módulos) |
/servicenow | Sincronização bidirecional com o CMDB do ServiceNow |
/events, /notifications | Trilha de auditoria e notificações do utilizador (incluindo stream SSE) |
Paginação, Filtragem e Ordenação
Os endpoints de listagem aceitam um conjunto consistente de parâmetros de consulta:
| Parâmetro | Descrição |
|---|---|
page | Número de página (baseado em 1) |
page_size | Itens por página (predefinição 50, máximo 200) |
sort_by | Campo pelo qual ordenar (por exemplo, name, updated_at) |
sort_dir | asc ou desc |
search | Filtro de texto livre (onde suportado) |
Os filtros específicos de cada recurso estão documentados por endpoint na referência da barra lateral (por exemplo, /cards aceita type, status, parent_id, approval_status).
Eventos em Tempo Real (Server-Sent Events)
GET /api/v1/events/stream é uma ligação SSE de longa duração que envia eventos à medida que ocorrem (cartão criado, atualizado, aprovado, etc.). A interface web utiliza-a para atualizar indicadores e listas sem polling. Qualquer cliente HTTP que suporte SSE pode subscrever — útil para construir dashboards em tempo real ou pontes de notificação externas.
Geração de Código
Como a API é totalmente descrita pelo OpenAPI 3.1, pode gerar clientes com tipagem segura em qualquer linguagem principal:
# Descarregar o esquema
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json
# Gerar um cliente Python
openapi-generator-cli generate \
-i canopy-openapi.json \
-g python \
-o ./canopy-client-py
# …ou TypeScript, Go, Java, C#, etc.
Para automação em Python, o caminho mais simples é geralmente utilizar httpx ou requests com chamadas escritas manualmente — a API é suficientemente pequena para que um gerador raramente valha a dependência.
Limitação de Taxa
Os endpoints sensíveis à autenticação (início de sessão, registo, redefinição de palavra-passe) têm limitação de taxa para proteção contra ataques de força bruta. Os outros endpoints não têm atualmente limitação de taxa; para scripts de automação intensivos, implemente a limitação do lado do cliente.
Versionamento e Estabilidade
- A API é versionada através do prefixo
/api/v1. Uma alteração que quebre a compatibilidade introduziria/api/v2em paralelo. - Dentro do
v1, alterações aditivas (novos endpoints, novos campos opcionais) podem ser lançadas em versões menores e de correção. Remoções ou alterações de contrato estão reservadas para um incremento de versão principal. - A versão atual é reportada por
GET /api/healthpara que possa detetar atualizações a partir de automação.
Resolução de Problemas
| Problema | Solução |
|---|---|
401 Unauthorized | O token está em falta, malformado ou expirado. Volte a autenticar-se via /auth/login ou /auth/refresh. |
403 Forbidden | O token é válido mas o utilizador não tem a permissão necessária. Verifique a função do utilizador em Utilizadores e Funções. |
422 Unprocessable Entity | A validação Pydantic falhou. O corpo da resposta lista quais os campos inválidos e porquê. |