Endereços da API local

Esta página lista cada endereço da API local, agrupado por assunto. Ela é para quem escreve um programa ou script. Para pedir a um assistente de IA, basta conectar o MCP: o assistente recebe esta lista sozinho.

O endereço base é http://127.0.0.1:5280 no próprio computador. De outro aparelho da mesma rede, troque 127.0.0.1 pelo IP do computador que mostra Configurações → API local. A porta é a que aparece nessa seção.

O próprio Studio SHC entrega esta lista no formato OpenAPI, em GET /v1/openapi.json. O formato completo do preset está em GET /v1/schemas/preset.json.

Como chamar

• Primeira chamada: abre a janela Permitir no Studio. Depois de permitir, a resposta traz a chave do programa no cabeçalho X-Shc-Chave.
• Chamadas seguintes: do mesmo aparelho e do mesmo programa, passam sem janela. De outro aparelho ou de outro programa, mande a chave em Authorization: Bearer SUA_CHAVE.
• Nome na janela: o cabeçalho X-Shc-Cliente é opcional. Ele só dá o nome do programa na janela Permitir.
• Corpo: JSON, com Content-Type: application/json, até 1 MiB. O pedido inteiro precisa chegar em 10 segundos.
• Campos do corpo: mande só os campos listados no endereço. Campo desconhecido é recusado com o erro 422.
• Repetir uma escrita: mande o mesmo Idempotency-Key (opcional). A segunda vez devolve a mesma resposta, sem executar de novo, por até 1 hora.
• Navegador: chamadas de uma página web (com o cabeçalho Origin) são recusadas.

Os detalhes de permissão estão em A janela Permitir.

Erros

Todo erro volta neste formato. O campo campos só aparece quando o problema é de um campo do corpo:

{
  "erro": {
    "codigo": "VALIDACAO",
    "mensagem": "O preset tem 1 problema.",
    "campos": {
      "comandos[0].nome": "Comando 1: informe o nome."
    }
  }
}

Código HTTP	codigo	Quando acontece
403	NAO_PERMITIDO	Sem permissão: janela “Permitir” recusada ou sem resposta, página web (cabeçalho Origin), Host inválido, ninguém logado, perfil sem acesso, não é o dono ou função desligada.
404	NAO_ENCONTRADO	Não encontrado.
405	METODO_NAO_PERMITIDO	Método não aceito aqui (a tela não faz isso); o motivo vem na mensagem.
408	PEDIDO_LENTO	O pedido demorou demais para chegar.
409	CONFLITO	Conflito com o estado atual (equipamento travado, preset despublicado, envio direto indisponível).
413	CORPO_GRANDE	Corpo acima de 1 MiB.
422	VALIDACAO	Dados inválidos; campos traz o problema de cada um.
500	INTERNO	Erro interno (detalhe só nos logs do app).
400 (MCP)	JSON-RPC	Pedido MCP inválido: erro JSON-RPC com code -32700 (corpo não é JSON) ou -32600 (mensagem inválida, lote, initialize sem id, sessão ausente, versão do protocolo).
404 (MCP)	JSON-RPC	Sessão MCP não encontrada (a API local foi religada, ou a sessão foi encerrada): erro JSON-RPC com code -32001. Comece de novo com initialize.
406 (MCP)	JSON-RPC	O cliente MCP não aceita application/json: erro JSON-RPC com code -32600.

Os erros 403, 408, 413 e 500 podem acontecer em qualquer endereço. Em cada endereço abaixo aparecem só os outros.

Lista dos endereços

Método	Endereço	O que faz
GET	/v1/saude	Testa a conexão
GET	/v1/comunicacao	UDP, TCP e interfaces de rede do Studio
GET	/v1/logs	Logs do Studio, com segredos mascarados
GET	/v1/openapi.json	Esta especificação (OpenAPI 3.1)
GET	/v1/schemas/preset.json	JSON Schema (2020-12) do preset
POST	/mcp	Servidor MCP (Streamable HTTP)
DELETE	/mcp	Encerra a sessão MCP
GET	/v1/presets	Lista os presets da biblioteca
POST	/v1/presets	Cria um preset
POST	/v1/presets/validar	Valida um preset sem gravar
POST	/v1/presets/testar-comando	Testa um comando do rascunho na rede, sem gravar
GET	/v1/presets/{id}	Mostra um preset completo
PATCH	/v1/presets/{id}	Edita (republica) um preset
DELETE	/v1/presets/{id}	Exclui um preset
POST	/v1/presets/{id}/publicar	Republica um preset despublicado
POST	/v1/presets/{id}/despublicar	Despublica um preset
GET	/v1/presets/{id}/avaliacao	A avaliação do usuário logado neste preset
PUT	/v1/presets/{id}/avaliacao	Avalia o preset em nome do usuário logado (Salvar nota)
DELETE	/v1/presets/{id}/avaliacao	Remove a avaliação do usuário logado (Remover nota)
GET	/v1/projects	Lista os projetos
POST	/v1/projects	Cria um projeto (Novo projeto)
GET	/v1/projects/{id}	Mostra um projeto
PATCH	/v1/projects/{id}	Altera nome e descrição do projeto
POST	/v1/projects/{id}/presets/{presetId}/aplicar	Adiciona um aparelho de preset ao projeto
POST	/v1/projects/{id}/comandos/{comandoId}/executar	Executa um comando de aparelho de preset
POST	/v1/projects/{id}/abrir	Abre o projeto no Studio, trocando a tela da pessoa
PUT	/v1/projects/{id}/imagem	Define a imagem do projeto (cor ou PNG/JPEG)
POST	/v1/projects/{id}/compartilhamentos	Compartilha o projeto com outra conta
DELETE	/v1/projects/{id}/compartilhamentos/{uid}	Tira uma conta do compartilhamento (Remover usuário)
GET	/v1/projects/{id}/planta	Lê a planta 2D do projeto (tab Visual)
PUT	/v1/projects/{id}/planta	Grava a planta 2D inteira (Salvar planta)
GET	/v1/projects/{id}/resumo	Resumo do projeto (métricas do Dashboard)
GET	/v1/projects/{id}/problemas	O que precisa de atenção no projeto (Dashboard)
GET	/v1/projects/{id}/rede/trafego	Pacotes na rede, com segredos mascarados (Tráfego na rede)
GET	/v1/projects/{id}/devices	Lista os equipamentos
POST	/v1/projects/{id}/devices	Adiciona um equipamento da rede ao projeto
GET	/v1/projects/{id}/devices/{deviceId}	Mostra um equipamento ou aparelho de preset
PATCH	/v1/projects/{id}/devices/{deviceId}	Renomeia um equipamento ou edita um aparelho de preset
DELETE	/v1/projects/{id}/devices/{deviceId}	Remove um equipamento ou aparelho de preset do projeto
GET	/v1/projects/{id}/devices/{deviceId}/configs	Lista as configurações do equipamento
GET	/v1/projects/{id}/devices/{deviceId}/configs/{configId}	Mostra uma configuração do equipamento
PATCH	/v1/projects/{id}/devices/{deviceId}/configs/{configId}	Altera uma configuração do equipamento
GET	/v1/projects/{id}/devices/{deviceId}/divergencia	Vê o que difere entre equipamento e nuvem
POST	/v1/projects/{id}/devices/{deviceId}/divergencia/resolver	Resolve a divergência, sobrescrevendo um dos lados
POST	/v1/projects/{id}/devices/{deviceId}/checkers	Confere de novo equipamento e nuvem (checkers)
POST	/v1/projects/{id}/devices/{deviceId}/conectar	Tenta conectar o equipamento (botão Conectar)
GET	/v1/projects/{id}/devices/{deviceId}/descricoes	Quantas descrições o equipamento tem na nuvem
POST	/v1/projects/{id}/devices/{deviceId}/descricoes/recarregar	Recarrega as descrições do equipamento
GET	/v1/projects/{id}/rede/equipamentos	Equipamentos que responderam na rede local
POST	/v1/projects/{id}/rede/descobrir	Procura equipamentos na rede local (botão de atualizar)
POST	/v1/projects/{id}/rede/localizar	Procura equipamentos numa faixa de IPs (Localizar por IP)
POST	/v1/projects/{id}/rede/localizar/{execucaoId}/parar	Para uma localização por IP em andamento
GET	/v1/projects/{id}/devices/{deviceId}/exportar	JSON com cenas, configurações e nomes do equipamento (Exportar)
POST	/v1/projects/{id}/devices/{deviceId}/importar	Substitui cenas, configurações e nomes do equipamento (Importar)
GET	/v1/projects/{id}/devices/{deviceId}/acesso-externo	Vinculação e uso do acesso externo (card da tela)
POST	/v1/projects/{id}/devices/{deviceId}/acesso-externo/vincular	Vincula o equipamento ao acesso externo deste projeto (Vincular)
POST	/v1/projects/{id}/devices/{deviceId}/exportacao	Coleta cenas e configurações de um equipamento legacy
GET	/v1/projects/{id}/devices/{deviceId}/firmware	Versões de firmware do equipamento (só consulta)
GET	/v1/projects/{id}/rooms	Lista os ambientes
POST	/v1/projects/{id}/rooms	Cria um ambiente
GET	/v1/projects/{id}/rooms/{roomId}	Mostra um ambiente
PATCH	/v1/projects/{id}/rooms/{roomId}	Renomeia um ambiente
DELETE	/v1/projects/{id}/rooms/{roomId}	Exclui um ambiente
PUT	/v1/projects/{id}/rooms/{roomId}/fundo	Define o fundo (imagem ou cor) do ambiente
GET	/v1/projects/{id}/inputs	Lista as entradas (botões)
GET	/v1/projects/{id}/inputs/{inputId}	Mostra uma entrada
PATCH	/v1/projects/{id}/inputs/{inputId}	Muda o nome e/ou o ambiente de uma entrada
GET	/v1/projects/{id}/outputs	Lista as saídas
GET	/v1/projects/{id}/outputs/{outputId}	Mostra uma saída
PATCH	/v1/projects/{id}/outputs/{outputId}	Muda nome, ambiente, ícone, oculta e categoria de uma saída
GET	/v1/projects/{id}/outputs/{outputId}/controladores	Botões que controlam uma saída (Controlado por)
DELETE	/v1/projects/{id}/outputs/{outputId}/controladores/{inputId}	Tira um botão do controle da saída (Remover associação)
GET	/v1/projects/{id}/scenes	Resumo das ações de cada botão
GET	/v1/projects/{id}/scenes/{inputId}	Ações de clique e de segurar de um botão
GET	/v1/projects/{id}/scenes/{inputId}/acoes	Ações de clique e de segurar de um botão
POST	/v1/projects/{id}/scenes/{inputId}/acoes	Adiciona ações a um botão
GET	/v1/projects/{id}/scenes/{inputId}/acoes/{n}	Mostra uma ação do botão
PATCH	/v1/projects/{id}/scenes/{inputId}/acoes/{n}	Muda os valores de uma ação do botão
DELETE	/v1/projects/{id}/scenes/{inputId}/acoes/{n}	Apaga uma ação do botão
POST	/v1/projects/{id}/scenes/{inputId}/recarregar	Recarrega as ações do botão a partir do equipamento
POST	/v1/projects/{id}/scenes/{inputId}/resetar	Apaga todas as ações do botão
POST	/v1/projects/{id}/scenes/{inputId}/importar	Substitui as ações de um gesto (o “Colar”)
GET	/v1/projects/{id}/scenes/{inputId}/agendamento	Mostra o agendamento do botão
PATCH	/v1/projects/{id}/scenes/{inputId}/agendamento	Altera o agendamento do botão
GET	/v1/projects/{id}/sincronizar	Pendências de envio aos equipamentos
POST	/v1/projects/{id}/sincronizar	Envia as pendências aos equipamentos (Atualizar tudo)
GET	/v1/projects/{id}/execucoes/{execucaoId}	Acompanha um trabalho em segundo plano (resposta 202)
GET	/v1/projects/{id}/inputs/ultimo-pressionado	Qual botão foi pressionado por último
POST	/v1/projects/{id}/outputs/{outputId}/acionar	Aciona uma saída agora (liga, desliga, ajusta)
POST	/v1/projects/{id}/inputs/{inputId}/executar	Executa as ações de um botão, como apertar a tecla
POST	/v1/projects/{id}/scenes/{inputId}/simular	Simula as ações do botão (Acender/Apagar)
GET	/v1/projects/{id}/devices/{deviceId}/atualizacao	Vê se há versão nova do preset (só leitura)
GET	/v1/projects/{id}/devices/{deviceId}/usos	Botões que usam os comandos do aparelho
POST	/v1/projects/{id}/devices/{deviceId}/parear	Pareia o aparelho (alguém aceita na tela dele)
GET	/v1/projects/{id}/devices/{deviceId}/pareamento	Situação do pareamento
DELETE	/v1/projects/{id}/devices/{deviceId}/pareamento	Desfaz o pareamento (apaga o token salvo)
GET	/v1/projects/{id}/devices/{deviceId}/estado	Pergunta o estado ao aparelho agora
DELETE	/v1/projects/{id}/scenes/{inputId}/comandos-removidos/{removidoId}	Dispensa o aviso de comando removido do botão
GET	/v1/projects/{id}/cenas-do-app	Lista as Cenas do App
POST	/v1/projects/{id}/cenas-do-app	Cria uma Cena do App
GET	/v1/projects/{id}/cenas-do-app/{cenaId}	Vê uma Cena do App
PATCH	/v1/projects/{id}/cenas-do-app/{cenaId}	Muda nome e emoji da Cena do App
DELETE	/v1/projects/{id}/cenas-do-app/{cenaId}	Exclui a Cena do App
POST	/v1/projects/{id}/cenas-do-app/{cenaId}/acoes	Adiciona ações à Cena do App
DELETE	/v1/projects/{id}/cenas-do-app/{cenaId}/acoes/{acaoId}	Remove uma ação da Cena do App
POST	/v1/projects/{id}/cenas-do-app/{cenaId}/executar	Executa a Cena do App agora

Conexão e documentação

Testa a conexão

GET /v1/saude

Responde ok e a versão do Studio SHC. Útil para conferir a chave do programa e a permissão no Studio.

Ferramenta MCP: verificar_api.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
ok	true ou false
versao	texto	Versão do app.

Exemplo:

{
  "ok": true,
  "versao": "1.0.5+8"
}

UDP, TCP e interfaces de rede do Studio

GET /v1/comunicacao

Se o UDP e o TCP estão ativos e quais interfaces de rede existem, com a selecionada. Ajuda a explicar um envio que falha. Só leitura: trocar de interface fica na tela, pois corta a comunicação.

Ferramenta MCP: ver_comunicacao.

Resposta 200 (Sucesso)

Exemplo:

{
  "udpAtivo": true,
  "tcpAtivo": true,
  "interfaces": [
    {
      "nome": "en0",
      "endereco": "192.168.1.10",
      "selecionada": true
    }
  ],
  "interfaceSelecionada": "192.168.1.10",
  "motivoSemRedeLocal": null
}

Logs do Studio, com segredos mascarados

GET /v1/logs

As linhas mais recentes dos “Logs do app”, da mais antiga à mais nova. O Studio guarda só as últimas 1000, em memória. Senhas, tokens e chaves saem como ***. Linha longa é cortada em 2000 caracteres e a resposta para quando o texto das linhas soma 256 K caracteres (cortadaPorTamanho). total conta as que casam com a busca. Limpar fica na tela.

Ferramenta MCP: ver_logs.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
busca	consulta	não	Só as linhas com este texto, procurado já com os segredos mascarados.
limite	consulta	não	De 1 a 1000; padrão 200.

Resposta 200 (Sucesso)

Exemplo:

{
  "logs": [
    {
      "momento": "2026-10-30T12:00:00.000Z",
      "mensagem": "[ApiLocal] execução 9f3a (sincronizar): concluida"
    }
  ],
  "total": 1,
  "devolvidos": 1,
  "cortadaPorTamanho": false
}

Outros erros possíveis: 422.

Esta especificação (OpenAPI 3.1)

GET /v1/openapi.json

Gerada a partir das rotas registradas e da documentação de cada uma.

Resposta 200 (Sucesso)

JSON Schema (2020-12) do preset

GET /v1/schemas/preset.json

Formato do preset aceito e devolvido pela API. A validação completa (a mesma da tela) é a do POST /v1/presets/validar.

Resposta 200 (Sucesso)

MCP

Servidor MCP (Streamable HTTP)

POST /mcp

Endpoint MCP (JSON-RPC 2.0; protocolo 2025-11-25, aceita 2025-06-18 e 2025-03-26): initialize, notifications/initialized, ping, tools/list e tools/call. Cada ferramenta chama a rota da API que ela espelha, com a mesma permissão. O initialize sem chave (e sem o mesmo IP e User-Agent de um programa já permitido) abre a janela “Permitir” no Studio; a sessão vem no cabeçalho Mcp-Session-Id da resposta e vale até DELETE /mcp, a API ser desligada, a porta ser trocada, a conta do Studio mudar, o Studio fechar ou o programa ser revogado.

Resposta 200 (Sucesso)

Resposta JSON-RPC 2.0 (202 sem corpo para notificações).

Outros erros possíveis: 400, 404, 406.

Encerra a sessão MCP

DELETE /mcp

Encerra a sessão do cabeçalho Mcp-Session-Id.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 204 (Sucesso, sem corpo)

Sem conteúdo.

Outros erros possíveis: 400, 404.

Presets

Lista os presets da biblioteca

GET /v1/presets

Lista a biblioteca de presets em páginas, em ordem de nome, como a tab Presets mostra. Use limite (padrão 50, máximo 200) e, para a página seguinte, cursor com o proximoCursor da resposta; proximoCursor null quer dizer que acabou. Um preset renomeado entre as chamadas pode aparecer de novo numa página seguinte: tire repetidos pelo id. total é quantos presets o filtro alcança (null quando há busca). Despublicados só aparecem para administradores. Filtros opcionais por fabricante (nome inteiro), categoria e texto (nome, fabricante, linha, modelos). Exige acesso à tab Presets. Categoria desconhecida, limite fora de 1 a 200 ou cursor malformado dão 422.

Ferramenta MCP: listar_presets.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
fabricante	consulta	não	Fabricante: o nome inteiro, sem diferenciar maiúsculas, acentos e pontuação.
categoria	consulta	não	Categoria. Valores: tv, receiver, multiroom, projetor, matrizVideo, arCondicionado, cortina, bridgeIrRf, releWifi, cameraNvr, mediaPlayer, generico.
busca	consulta	não	Texto livre.
limite	consulta	não	Presets por página, de 1 a 200; padrão 50.
cursor	consulta	não	Opaco: o proximoCursor da página anterior. Sem ele, começa do início.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
presets	lista	Resumo de cada preset (id, nome, fabricante, categoria, linhaSerie, modelosCompativeis, descricao, statusConfianca, versao, publicado, autor, ratingMedia, ratingCount, quantidadeComandos, updatedAt), sem os comandos.
total	inteiro ou null	Quantos presets o filtro alcança (sem os despublicados, para quem não é administrador); null quando há busca.
proximoCursor	texto ou null	Cursor da próxima página; null no fim.

Exemplo:

{
  "presets": [
    {
      "id": "p1",
      "nome": "Samsung TV Tizen 2020+ (IP Control)",
      "fabricante": "Samsung",
      "categoria": "tv",
      "versao": 4,
      "publicado": true,
      "quantidadeComandos": 9
    }
  ],
  "total": 1,
  "proximoCursor": null
}

Outros erros possíveis: 422.

Cria um preset

POST /v1/presets

Cria e publica um preset novo na biblioteca, com a mesma validação e as mesmas permissões da tela: só revenda e administrador criam, e com a criação suspensa só o administrador. O app calcula id, versão (1), autor e os campos de busca; se vierem no corpo, são ignorados com aviso. Chave desconhecida é recusada. Valide antes com validar_preset.

Ferramenta MCP: criar_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Tipo: Preset.

Resposta 201 (Criado)

Campo	Tipo	O que traz
id	texto	Id do preset.
versao	inteiro
publicado	true ou false
autor	objeto
derivados	objeto	Campos que o app calcula (nomeKey, fabricanteKey, buscaTokens, chaveDuplicata).
permissoes	objeto	O que o usuário logado pode fazer: editar, remover, moderar.
preset	Preset
avisos	lista de texto	Só em criar/editar: campos calculados ignorados, transporte/tcp do formato antigo descartados, ordem renumerada, index de comando existente mantido, comandos removidos.

Outros erros possíveis: 422.

Valida um preset sem gravar

POST /v1/presets/validar

Roda a mesma validação da tela (validarPreset) e devolve valido, os problemas por campo (campos, com caminho como comandos[0].acoes[1].corpoHttp) e os campos derivados. Nada é gravado. Sem presetId valida como criação; com ?presetId=X valida como a edição de X (merge patch, nota da versão obrigatória e “nada mudou”). Responde 200 mesmo quando o preset é inválido; 422 só quando nem dá para montar o preset (corpo não JSON, tipo errado, categoria ou statusConfianca desconhecidos). Exige só acesso à tab Presets. presetId inexistente, ou de um preset despublicado para quem não é admin: 404.

Ferramenta MCP: validar_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
presetId	consulta	não	Valida como edição deste preset.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Tipo: Preset. O preset (criação) ou o merge patch (edição).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
valido	true ou false
campos	objeto
erros	lista de texto
derivados	objeto
avisos	lista de texto

Exemplo:

{
  "valido": false,
  "campos": {
    "comandos[0].nome": "Comando 1: informe o nome."
  },
  "erros": [
    "Comando 1: informe o nome."
  ],
  "derivados": {
    "versao": 1
  },
  "avisos": []
}

Outros erros possíveis: 404, 422.

Testa um comando do rascunho na rede, sem gravar

POST /v1/presets/testar-comando

O Testar do editor: o app abre a conexão com o aparelho indicado no comando (com os valores informados) e nada é gravado. Só quem pode criar preset (revenda ou administrador; com a criação suspensa, só administrador). Exige o app instalado (no navegador, 409). Vale a validação do preset e dos campos, e os destinos proibidos continuam proibidos. Resposta mascarada; do que o comando capturar, só os nomes (camposCapturados): o valor fica na memória do Studio para os próximos testes, até ele fechar.

Ferramenta MCP: testar_comando_de_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
preset	Preset	sim	O rascunho do preset.
comandoId	texto	sim	Id do comando.
valores	objeto	não	Valores dos campos do comando. Campo omitido usa o valor padrão; campo de pareamento usa o token capturado por um teste anterior.

Resposta 200 (Sucesso)

Exemplo:

{
  "ok": true,
  "erro": null,
  "passosExecutados": 1,
  "tokenRecusado": false,
  "resposta": "",
  "lidos": [],
  "camposCapturados": [],
  "gravado": false
}

Outros erros possíveis: 409, 422.

Mostra um preset completo

GET /v1/presets/{id}

Devolve o preset com comandos, ações, campos e comunicação (no formato do JSON Schema /v1/schemas/preset.json), as permissões do usuário logado e os campos derivados. Preset despublicado só para administrador, como na listagem: para os demais, 404.

Ferramenta MCP: ver_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	Id do preset.
versao	inteiro
publicado	true ou false
autor	objeto
derivados	objeto	Campos que o app calcula (nomeKey, fabricanteKey, buscaTokens, chaveDuplicata).
permissoes	objeto	O que o usuário logado pode fazer: editar, remover, moderar.
preset	Preset
avisos	lista de texto	Só em criar/editar: campos calculados ignorados, transporte/tcp do formato antigo descartados, ordem renumerada, index de comando existente mantido, comandos removidos.

Outros erros possíveis: 404.

Edita (republica) um preset

PATCH /v1/presets/{id}

Aplica um JSON Merge Patch (RFC 7386: objeto mescla, null apaga, lista substitui inteira) e republica com versão + 1. Exige notasDaVersao (até 300 caracteres) e alguma mudança. Só o autor edita, e só se for revenda ou administrador. A ordem dos comandos e das ações é a posição no corpo.

Ferramenta MCP: editar_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
nome	texto ou null	não	Nome do equipamento controlado.
fabricante	texto ou null	não	Fabricante.
categoria	tv, receiver, multiroom, projetor, matrizVideo, arCondicionado, cortina, bridgeIrRf, releWifi, cameraNvr, mediaPlayer, generico ou null	não	Categoria do equipamento.
linhaSerie	texto ou null	não	Linha ou série.
modelosCompativeis	texto ou null	não	Modelos compatíveis.
faixaFirmwareAno	texto ou null	não	Faixa de firmware ou ano.
descricao	texto ou null	não	O que o preset controla e como preparar o equipamento.
variaveis	lista de PresetVariavel ou null	não	Campos que o instalador preenche ao aplicar o preset, usados como {{nome}} nos comandos.
comandos	lista de PresetComando (mín. 1 item) ou null	não	Comandos do preset.
statusConfianca	rascunho, testadoEmCampo ou null	não	Auto-declarado pelo autor.
notasDaVersao	texto	sim	O que mudou nesta versão (obrigatória).
presetOrigemId	texto ou null	não	Preset do qual este foi derivado.
comunicacao	PresetComunicacao ou objeto ou null	não	Como o app conversa com o aparelho: formato, tempos, autorizações, regras de resposta, corpo em erro HTTP e chaves sensíveis. As leituras ficam em comandos[i].leituras.
motorMinimo	inteiro ou null	não	Versão mínima do motor de disparo (reservado).
transporte	texto ou null	não	Formato antigo (transporte no topo); descartado com aviso. Hoje o transporte é de cada ação.
tcp	objeto ou null	não	Formato antigo (destino TCP no topo); descartado com aviso. Hoje o destino é de cada ação.

Calculados pelo Studio (se vierem no corpo, são ignorados): nomeKey, fabricanteKey, buscaTokens, chaveDuplicata, versao, id, presetId, uid, autorUid, autorNome, autorVerificado, disabled, ratingMedia, ratingCount, ratingSoma, createdAt, updatedAt.

Exemplo:

{
  "notasDaVersao": "Corrige o comando Desligar.",
  "descricao": "Controle pela rede oficial da Samsung (IP Control)."
}

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	Id do preset.
versao	inteiro
publicado	true ou false
autor	objeto
derivados	objeto	Campos que o app calcula (nomeKey, fabricanteKey, buscaTokens, chaveDuplicata).
permissoes	objeto	O que o usuário logado pode fazer: editar, remover, moderar.
preset	Preset
avisos	lista de texto	Só em criar/editar: campos calculados ignorados, transporte/tcp do formato antigo descartados, ordem renumerada, index de comando existente mantido, comandos removidos.

Outros erros possíveis: 404, 422.

Exclui um preset

DELETE /v1/presets/{id}

Como o “Excluir preset” da tela: só o autor, e só se for revenda ou administrador; apaga o documento. Aparelhos já instalados guardam a cópia deles.

Ferramenta MCP: remover_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	Id excluído.
removido	true ou false

Outros erros possíveis: 404.

Republica um preset despublicado

POST /v1/presets/{id}/publicar

Só administrador. Volta o preset para a biblioteca.

Ferramenta MCP: publicar_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	Id.
publicado	true ou false

Outros erros possíveis: 404.

Despublica um preset

POST /v1/presets/{id}/despublicar

Só administrador. Tira o preset da biblioteca sem apagar.

Ferramenta MCP: despublicar_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	Id.
publicado	true ou false

Outros erros possíveis: 404.

A avaliação do usuário logado neste preset

GET /v1/presets/{id}/avaliacao

A nota e o comentário que o usuário deu, se deu; podeAvaliar e motivo dizem se ele pode avaliar; ratingMedia e ratingCount são os da biblioteca.

Ferramenta MCP: ver_minha_avaliacao_de_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "p1",
  "avaliado": true,
  "nota": 4,
  "descricao": "Funcionou bem",
  "comentario": "",
  "podeAvaliar": true,
  "motivo": null,
  "ratingMedia": 4.5,
  "ratingCount": 2
}

Outros erros possíveis: 404.

Avalia o preset em nome do usuário logado (Salvar nota)

PUT /v1/presets/{id}/avaliacao

Nota de 1 a 5, em nome do usuário logado: só use a pedido dele. Reavaliar substitui. Notas 1 a 3 exigem comentario com o motivo; 4 e 5 não levam comentário. Fora disso: 422. Quem publicou o preset não avalia: 403. Preset despublicado: 409.

Ferramenta MCP: avaliar_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
nota	inteiro (mín. 1, máx. 5)	sim
comentario	texto	não	Motivo, até 500 caracteres. Só com nota de 1 a 3.

Exemplo:

{
  "nota": 2,
  "comentario": "Só funcionou na porta 23."
}

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "p1",
  "nota": 2,
  "descricao": "Funcionou com dificuldade",
  "comentario": "Só funcionou na porta 23.",
  "mensagem": "Avaliação gravada."
}

Outros erros possíveis: 404, 409, 422.

Remove a avaliação do usuário logado (Remover nota)

DELETE /v1/presets/{id}/avaliacao

Só o próprio voto, em nome do usuário logado. Sem avaliação: 404. Quem publicou: 403. Preset despublicado: 409.

Ferramenta MCP: remover_minha_avaliacao_de_preset.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do preset (campo “id” da listagem).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "p1",
  "removida": true
}

Outros erros possíveis: 404, 409.

Projetos

Lista os projetos

GET /v1/projects

Projetos da lista do usuário logado (próprios e compartilhados), com ehDono/podeEditar. Só o dono altera.

Ferramenta MCP: listar_projetos.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
projetos	lista	id, nome, descricao, ehDono, podeEditar.
total	inteiro

Exemplo:

{
  "projetos": [
    {
      "id": "abc123",
      "nome": "Casa da Praia",
      "ehDono": true
    }
  ],
  "total": 1
}

Cria um projeto (Novo projeto)

POST /v1/projects

O mesmo “Novo projeto” da lista, sem licença, imagem nem compartilhamento (há rotas para os dois últimos). O usuário logado vira o dono. Espera o projeto chegar à lista do Studio (até cerca de 10 s) e responde 201 de qualquer forma: naLista true, pronto para abrir_projeto; naLista false (com aviso): ainda não chegou. Atenção: projeto criado só se exclui à mão no Studio. Nome vazio: 422. Sem internet ou recusa do servidor: 409.

Ferramenta MCP: criar_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
nome	texto	sim	Nome do projeto, não vazio.
descricao	texto	não	Descrição (opcional).

Exemplo:

{
  "nome": "Casa da Praia",
  "descricao": "Reforma"
}

Resposta 201 (Criado)

Exemplo:

{
  "id": "abc123",
  "nome": "Casa da Praia",
  "descricao": "Reforma",
  "ehDono": true,
  "podeEditar": true,
  "naLista": true
}

Outros erros possíveis: 409, 422.

Mostra um projeto

GET /v1/projects/{id}

Projeto, abertoNoStudio (se é o projeto aberto agora no Studio) e os recursos que o perfil do usuário acessa (devices, inputs, scenes, outputs, rooms, presets). Só para o dono cujo perfil vê a aba Projeto: acesso, com usuarios (uid, email, nome; email e nome null se a conta não foi achada) e licencas (id, ativa), em leitura.

Ferramenta MCP: ver_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Altera nome e descrição do projeto

PATCH /v1/projects/{id}

Como o “Salvar” da tela Projeto, mas só grava o que veio: não mexe em imagem, compartilhamento nem licenças. Só o dono; sem a aba Projeto no perfil ou com ela desligada: 403. Se a tela Projeto estiver aberta no Studio, ela não recarrega: reabra antes de salvar por lá.

Ferramenta MCP: editar_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Mande pelo menos 1 campo: o corpo vazio é recusado.

Campo	Tipo	Obrigatório	Para que serve
nome	texto	não	Nome novo, não vazio.
descricao	texto	não	Descrição nova (pode ser vazia).

Exemplo:

{
  "nome": "Casa da Praia 2"
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 422.

Adiciona um aparelho de preset ao projeto

POST /v1/projects/{id}/presets/{presetId}/aplicar

O “Adicionar ao projeto” do preset: só o dono, preset publicado, os mesmos campos e a mesma validação da janela. O pareamento não acontece aqui (precisa de alguém aceitando na tela do aparelho): preset com pareamento volta com pareamentoPendente.

Ferramenta MCP: aplicar_preset_no_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
presetId	caminho	sim	Id do preset.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
nome	texto	não	Nome do aparelho (padrão: o nome do preset).
variaveis	objeto	não	Campos que o preset pede na instalação (ex.: {“ip”: “192.168.1.50”}).
ambienteId	texto ou null	não	Ambiente do projeto.

Exemplo:

{
  "nome": "TV da Sala",
  "variaveis": {
    "ip": "192.168.1.50",
    "mac": "AA:BB:CC:DD:EE:FF"
  }
}

Resposta 201 (Criado)

Outros erros possíveis: 404, 409, 422.

Executa um comando de aparelho de preset

POST /v1/projects/{id}/comandos/{comandoId}/executar

Token recusado volta em tokenRecusado: a API nunca pareia sozinha, chame parear_aparelho com o comandoId. O clique no ícone da saída de preset: o Studio abre a conexão com o aparelho. comandoId é o id da saída (preset:{aparelho}:{comando}) ou o id do comando com aparelhoId no corpo. Não abre janelas. Pede a aba Saídas ou Dispositivos no perfil; convidado pode. O comando de pareamento (use parear_aparelho) e o de renovação de acesso (o Studio roda sozinho) dão 409, assim como o navegador sem o app instalado.

Ferramenta MCP: executar_comando.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
comandoId	caminho	sim	preset:{aparelho}:{comando}, ou o id do comando.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
aparelhoId	texto	não	Id do aparelho (com ou sem “preset:”), quando comandoId é só o id do comando.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
ok	true ou false
erro	texto ou null
passosExecutados	inteiro
tokenRecusado	true ou false
respondeu	true ou false
lidos	lista

Outros erros possíveis: 404, 409, 422.

Abre o projeto no Studio, trocando a tela da pessoa

POST /v1/projects/{id}/abrir

Faz o Studio ir para o projeto, como tocar nele na lista, e mostra um aviso na tela com o nome do programa. Responde quando o projeto está pronto para as escritas; se demorar, 202 e acompanhe abertoNoStudio em ver_projeto. Dono e convidado. Planta com edição não salva, janela “Atualizar devices” aberta ou envio em curso dão 409. Cuidado: quem está usando o Studio perde a tela atual.

Ferramenta MCP: abrir_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "h1",
  "abertoNoStudio": true,
  "jaEstavaAberto": false
}

Outros erros possíveis: 404, 409, 422.

Define a imagem do projeto (cor ou PNG/JPEG)

PUT /v1/projects/{id}/imagem

Como “Alterar” da tela Projeto: uma cor da paleta ({“cor”: “#FFB3BA”}) ou uma imagem PNG/JPEG em base64, até 512 KiB, que vai ao Storage ({“imagem”: {“base64”, “tipo”}}). A tela reduz a imagem para 800×800; a API não redimensiona: envie pronta. Só o dono. Falha no envio: 409, nada muda.

Ferramenta MCP: definir_imagem_do_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
cor	texto	não	Cor da paleta (#RRGGBB).
imagem	objeto	não
imagem.base64	texto	sim	Bytes da imagem em base64, sem “data:”.
imagem.tipo	image/png, image/jpeg	sim	Tipo.

Exemplo:

{
  "cor": "#BAE1FF"
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Compartilha o projeto com outra conta

POST /v1/projects/{id}/compartilhamentos

Dá a outra pessoa acesso de consulta e comando a este projeto: confirme o e-mail com o usuário antes. Só o dono. E-mail sem conta: 404 “Usuário não encontrado”, como a tela. Já compartilhado, ou a própria conta dona: 409. Lista atual em ver_projeto.

Ferramenta MCP: compartilhar_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
email	texto	sim	E-mail da conta do Studio SHC.

Exemplo:

{
  "email": "pessoa@exemplo.com"
}

Resposta 201 (Criado)

Exemplo:

{
  "usuario": {
    "uid": "u2",
    "email": "pessoa@exemplo.com",
    "nome": "Pessoa"
  },
  "totalDeUsuarios": 1
}

Outros erros possíveis: 404, 409, 422.

Tira uma conta do compartilhamento (Remover usuário)

DELETE /v1/projects/{id}/compartilhamentos/{uid}

A pessoa perde o acesso a este projeto na hora. Confirme com o usuário antes. Só o dono: quem recebeu o projeto não consegue sair por aqui. Conta que não está na lista: 404.

Ferramenta MCP: remover_usuario_do_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
uid	caminho	sim	uid da conta, de acesso.usuarios em ver_projeto.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Exemplo:

{
  "uid": "u2",
  "removido": true
}

Outros erros possíveis: 404.

Lê a planta 2D do projeto (tab Visual)

GET /v1/projects/{id}/planta

A planta gravada, descomprimida, e a revisao, base obrigatória de gravar_planta. Sem planta: temPlanta false e planta null. Só geometria: nome do ambiente, ambiente de cada item e ligações ficam em rooms, inputs, outputs e nas ações do botão. edicaoNaoSalvaNoStudio true: a pessoa está editando e gravar_planta será recusada. somenteLeitura true: gravada por uma versão mais nova do Studio. Dono e quem recebeu o projeto, com a aba Visual liberada; senão, 403.

Ferramenta MCP: ver_planta.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc123",
  "temPlanta": true,
  "revisao": 3,
  "somenteLeitura": false,
  "planta": {
    "schemaVersion": 2,
    "p": [
      {
        "i": "p1",
        "a": [],
        "it": [],
        "pr": [
          {
            "i": "w0",
            "a": [
              0,
              0
            ],
            "b": [
              300,
              0
            ]
          }
        ]
      }
    ],
    "pa": "p1"
  },
  "ambientes": 0,
  "itens": 0,
  "uso": {
    "bytesGravados": 280,
    "limiteBytes": 983040,
    "percentual": 0
  },
  "edicaoNaoSalvaNoStudio": false
}

Outros erros possíveis: 404, 409.

Grava a planta 2D inteira (Salvar planta)

PUT /v1/projects/{id}/planta

SUBSTITUI a planta inteira: leia com ver_planta, altere e devolva tudo com revisaoBase = a revisao lida (0 se não há planta). Coordenadas em cm inteiros. Sem revisaoBase ou com revisão diferente: 409 com campos.revisaoAtual: leia de novo e refaça (“Salvar mesmo assim” fica só na tela; o parâmetro substituir dá 422). Planta aberta com alteração não salva no Studio: 409, nada é gravado. Planta gravada por uma versão mais nova do Studio (somenteLeitura) ou sem conexão para gravar: 409. Formato: o mesmo de ver_planta, sem tolerância; schemaVersion diferente da deste Studio (mais nova ou mais antiga), campo desconhecido, valor padrão explícito, mais de um pavimento, pa que não é o pavimento, id repetido ou elemento inválido: 422 com o caminho do problema. Acima de 80% do espaço: 422. Como na tela, ao gravar saem os ícones de saídas e botões que não existem mais, os ambientes sem rooms/{id} (o r do ambiente é obrigatório) e as posições fora do ambiente do item; a resposta conta em podados. md, an, tx e gd (cotas, anotações, textos e guias) só se editam na tela: devolva-os como ver_planta entregou, diferentes é 422. Planta que ficaria sem desenho: 422, apagar fica só no Studio. Quem está com a tab Visual aberta e sem alterações recebe a planta nova. Só o dono.

Ferramenta MCP: gravar_planta.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
planta	objeto	sim	A planta, no formato de ver_planta.
planta.schemaVersion	inteiro	sim	Versão do formato, a de ver_planta.
planta.p	lista	sim	Exatamente um pavimento: i (id), a (ambientes), it (itens) e, opcionais, pr, pt, jn, es, co, md, an, tx, gd, gp, im.
planta.pa	texto	não	Id do pavimento ativo.
revisaoBase	inteiro	não	A revisao lida em ver_planta; 0 se não há planta.

Exemplo:

{
  "planta": {
    "schemaVersion": 2,
    "p": [
      {
        "i": "p1",
        "a": [],
        "it": [],
        "pr": [
          {
            "i": "w0",
            "a": [
              0,
              0
            ],
            "b": [
              300,
              0
            ]
          }
        ]
      }
    ],
    "pa": "p1"
  },
  "revisaoBase": 0
}

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc123",
  "revisao": 1,
  "ambientes": 0,
  "itens": 0,
  "podados": {
    "icones": 0,
    "ambientes": 0,
    "posicoesDescartadas": 0
  },
  "uso": {
    "bytesGravados": 280,
    "limiteBytes": 983040,
    "percentual": 0
  }
}

Outros erros possíveis: 404, 409, 422.

Resumo do projeto (métricas do Dashboard)

GET /v1/projects/{id}/resumo

Quantos equipamentos, online, semResposta (todo equipamento que não está online, o “Dispositivos Offline” da tela; procurando é a parte deles ainda sem nenhuma resposta), legados, entradas, saídas, ambientes, Cenas do App e pendências de envio. Evita percorrer as listas. Quem vê o Dashboard; senão, 403. Precisa do projeto aberto (409): é estado ao vivo.

Ferramenta MCP: ver_resumo_do_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc123",
  "equipamentos": 3,
  "online": 2,
  "semResposta": 1,
  "procurando": 1,
  "legados": 1,
  "entradas": 4,
  "saidas": 6,
  "saidasSemAmbiente": 6,
  "ambientes": 1,
  "ambientesVazios": 1,
  "cenasDoApp": 0,
  "pendencias": {
    "alteracoes": 2,
    "equipamentos": 1,
    "prontosParaEnvio": 1
  },
  "descricoes": {
    "carregando": 0,
    "comFalha": 0
  }
}

Outros erros possíveis: 404, 409.

O que precisa de atenção no projeto (Dashboard)

GET /v1/projects/{id}/problemas

acoes: botões com ação sem preset no projeto (acao_sem_preset, a ação continua funcionando) ou comando tirado do botão por não caber (comando_removido). alertas: equipamentos offline, sem ambiente, com firmware legado, com falha nas descrições ou com pendência pronta para envio. Ação já gravada fora do que a API aceita vem em acoesForaDaLista, com aviso. Quem vê o Dashboard; senão, 403. Precisa do projeto aberto (409): é estado ao vivo.

Ferramenta MCP: ver_problemas_do_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc123",
  "acoes": [
    {
      "entradaId": "devK-_cs_bt0",
      "equipamento": "Keypad",
      "botao": "Botão 1",
      "ambiente": "Sala",
      "gesto": "clique",
      "problema": "acao_sem_preset",
      "quantidade": 1
    }
  ],
  "alertas": [
    {
      "equipamentoId": "devL",
      "equipamento": "Keypad velho",
      "ambiente": null,
      "pendencias": 0,
      "motivos": [
        "Offline",
        "Sem ambiente",
        "Firmware legado"
      ]
    }
  ]
}

Outros erros possíveis: 404, 409.

Pacotes na rede, com segredos mascarados (Tráfego na rede)

GET /v1/projects/{id}/rede/trafego

Os últimos pacotes do monitor, do mais antigo ao mais novo, com o nome do equipamento quando o IP é deste projeto. O monitor é da rede inteira, não só do projeto; o Studio guarda só os últimos 200. A query inteira de /lb/wifi e /cf/*, o payload e campos com nome de senha, token ou chave saem como ***. Linha longa é cortada em 2000 caracteres e a resposta para quando o texto soma 256 K caracteres (cortadaPorTamanho). Enviar pacote não existe na API. Função desligada: 403. Sem rede local: 409.

Ferramenta MCP: ver_trafego_de_rede.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
busca	consulta	não	Só as linhas com este texto, procurado já com os segredos mascarados.
limite	consulta	não	De 1 a 200; padrão 100.

Resposta 200 (Sucesso)

Exemplo:

{
  "pacotes": [
    {
      "momento": "2026-10-30T12:00:00.000Z",
      "direcao": "enviado",
      "transporte": "tcp",
      "origem": "192.168.1.10",
      "origemNome": null,
      "destino": "192.168.1.20",
      "destinoNome": "Keypad",
      "pacote": "$ABCD>/lb/wifi@0?***<1#"
    }
  ],
  "total": 1,
  "devolvidos": 1,
  "cortadaPorTamanho": false,
  "contadores": {
    "udpEnviados": 0,
    "udpRecebidos": 0,
    "tcpEnviados": 1,
    "tcpRecebidos": 0
  }
}

Outros erros possíveis: 404, 409, 422.

Equipamentos

Lista os equipamentos

GET /v1/projects/{id}/devices

Equipamentos do projeto (com status online/offline do Studio, divergente — null com o projeto fechado no Studio — e capacidades) e os aparelhos de preset instalados.

Ferramenta MCP: listar_equipamentos.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
equipamentos	lista
aparelhosDePreset	lista	id “preset:{aparelho}”; comandos com o id da saída para executar_comando.
total	inteiro

Outros erros possíveis: 404.

Adiciona um equipamento da rede ao projeto

POST /v1/projects/{id}/devices

O “Adicionar ao projeto”. O equipamento precisa estar em listar_equipamentos_na_rede (404). Cria o equipamento no projeto e busca as descrições em segundo plano; acompanhe em ver_descricoes_do_equipamento. A gravação é a local do Studio: se a nuvem recusar depois, o erro só aparece nos logs. Só o dono. Já no projeto, mesmo ID ou a mesma adição ainda em curso: 409. Firmware anterior a 3.0.0 no IP do AP: 409, entra pelo Setup WiFi no Studio. Aparelho de preset: use aplicar_preset_no_projeto. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: adicionar_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
deviceId	texto	sim	deviceId da lista da rede.

Exemplo:

{
  "deviceId": "ABCD"
}

Resposta 201 (Criado)

Exemplo:

{
  "id": "k3Jd9",
  "deviceId": "ABCD",
  "nome": "Módulo"
}

Outros erros possíveis: 404, 409, 422.

Mostra um equipamento ou aparelho de preset

GET /v1/projects/{id}/devices/{deviceId}

deviceId é o docId do equipamento ou “preset:{id}” de um aparelho de preset.

Ferramenta MCP: ver_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId ou preset:{id}.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Renomeia um equipamento ou edita um aparelho de preset

PATCH /v1/projects/{id}/devices/{deviceId}

Só o dono do projeto. Equipamento: {“nome”}. Aparelho de preset (deviceId “preset:{id}”): {“nome”?, “variaveis”?}, como o Editar do aparelho — troca só o que vier, valida igual à tela e reaplica os valores novos nos botões que usam os comandos dele (resposta com botoes e a mesma mensagem da tela). Campos de pareamento não se editam aqui; senha aceita valor novo, nunca volta (mandar “***” é 422).

Ferramenta MCP: renomear_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento ou preset:{id}.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Mande pelo menos 1 campo: o corpo vazio é recusado.

Campo	Tipo	Obrigatório	Para que serve
nome	texto	não	Nome novo, não vazio.
variaveis	objeto	não	Só aparelho de preset: campos da instalação a trocar (ex.: {“ip”: “192.168.1.60”}).

Exemplo:

{
  "nome": "Teclado da Sala"
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 422.

Remove um equipamento ou aparelho de preset do projeto

DELETE /v1/projects/{id}/devices/{deviceId}

Equipamento: o “Remover do projeto” da tela (apaga o equipamento, as descrições, os nomes amigáveis, as cenas e os vínculos com ambientes). Aparelho de preset (“preset:{id}”): o Remover do aparelho — tira os comandos dele dos botões (pendente de envio) e apaga o aparelho; exige o projeto aberto no Studio com as ações carregadas (409). Só o dono.

Ferramenta MCP: remover_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento ou preset:{id}.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	docId ou preset:{id}.
removido	true ou false

Outros erros possíveis: 404, 409.

Lista as configurações do equipamento

GET /v1/projects/{id}/devices/{deviceId}/configs

As configurações /lb/* do detalhe do equipamento (sem /lb/buttons, que é o agendamento, nem /lb/wifi): parâmetros com tipo, valores e limites, e os valores gravados por índice.

Ferramenta MCP: listar_configuracoes_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
configs	lista
total	inteiro

Outros erros possíveis: 404.

Mostra uma configuração do equipamento

GET /v1/projects/{id}/devices/{deviceId}/configs/{configId}

Uma configuração /lb/* (configId como _lb_device).

Ferramenta MCP: ver_configuracao_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.
configId	caminho	sim	Id da configuração (GET …/configs).

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Altera uma configuração do equipamento

PATCH /v1/projects/{id}/devices/{deviceId}/configs/{configId}

Como o card de configuração do detalhe do equipamento: grava os valores no índice (padrão 0), conferidos pelo tipo de cada parâmetro. Trocar o ID do equipamento (parâmetro id) só pela tela (422). Legacy offline: 409. Só o dono. O equipamento só recebe quando o Studio sincroniza (pendenciasDeEnvio na resposta).

Ferramenta MCP: alterar_configuracao_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.
configId	caminho	sim	Id da configuração (GET …/configs).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
indice	inteiro (mín. 0)	não
valores	objeto	sim	Parâmetro → valor.

Exemplo:

{
  "valores": {
    "mode": "Normal"
  }
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Vê o que difere entre equipamento e nuvem

GET /v1/projects/{id}/devices/{deviceId}/divergencia

Os dados do diálogo “Dados divergentes”: quantas diferenças, quais, as datas e se dá para manter a nuvem. Projeto fechado no Studio dá 409 (use abrir_projeto).

Ferramenta MCP: ver_divergencia_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc",
  "nome": "Módulo",
  "divergente": true,
  "diferencas": 1,
  "itens": [
    {
      "caminho": "/cs/bt0",
      "tipo": "cena"
    }
  ],
  "nuvem": "Data da Nuvem indisponível",
  "equipamento": "Dispositivo alterado fora do app (sem registro de sincronização)",
  "podeManterNuvem": true
}

Outros erros possíveis: 404, 409.

Resolve a divergência, sobrescrevendo um dos lados

POST /v1/projects/{id}/devices/{deviceId}/divergencia/resolver

“equipamento” sobrescreve a nuvem com o que está no equipamento; “nuvem” sobrescreve o equipamento (a falha vira pendência). Responde 202 com execucaoId; ver_execucao traz sucesso ou falha por item. Não exige ser dono, como a tela. Precisa do app instalado, projeto aberto e equipamento online (409). Sem dados na nuvem, “nuvem” dá 409.

Ferramenta MCP: resolver_divergencia_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
manter	equipamento, nuvem	sim	Lado que fica.

Exemplo:

{
  "manter": "nuvem"
}

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Outros erros possíveis: 404, 409, 422.

Confere de novo equipamento e nuvem (checkers)

POST /v1/projects/{id}/devices/{deviceId}/checkers

O que o Studio faz ao entrar no projeto: moderno pergunta /if/checkers, legacy compara só as datas. Devolve a divergência atual. Equipamento offline ou projeto fechado dá 409.

Ferramenta MCP: rodar_checkers_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Tenta conectar o equipamento (botão Conectar)

POST /v1/projects/{id}/devices/{deviceId}/conectar

Envia /if/device por UDP e testa TCP (moderno) ou HTTP (legacy): é o que tira um legacy do bloqueio offline. A resposta traz a frase da tela e o status. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: conectar_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc",
  "conectou": true,
  "mensagem": "Tentativa enviada via UDP e TCP.",
  "status": "online",
  "online": true
}

Outros erros possíveis: 404, 409, 422.

Quantas descrições o equipamento tem na nuvem

GET /v1/projects/{id}/devices/{deviceId}/descricoes

O “n/total” da coluna Ações, e o andamento de um recarregar_descricoes_do_equipamento.

Ferramenta MCP: ver_descricoes_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Recarrega as descrições do equipamento

POST /v1/projects/{id}/devices/{deviceId}/descricoes/recarregar

O “Recarregar” da tela. Com todas na nuvem, APAGA e pede de novo (só o dono); faltando alguma, só pede de novo, sem apagar. Equipamento offline dá 409 sem apagar nada; descrições já sendo carregadas também dão 409. Precisa do app instalado e do projeto aberto (409). Responde 202; acompanhe em ver_descricoes_do_equipamento.

Ferramenta MCP: recarregar_descricoes_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	docId do equipamento.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Exemplo:

{
  "id": "abc",
  "limpou": true,
  "acompanhar": "/v1/projects/h1/devices/abc/descricoes"
}

Outros erros possíveis: 404, 409, 422.

Equipamentos que responderam na rede local

GET /v1/projects/{id}/rede/equipamentos

A lista “Dispositivos na Rede”, mais os que já estão no projeto (noProjeto e idNoProjeto). podeAdicionar diz se adicionar_equipamento aceitaria e recusaAoAdicionar, o motivo. modoAp: está no IP do AP de configuração. Lista vazia: use descobrir_equipamentos_na_rede. Convidado pode. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: listar_equipamentos_na_rede.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Exemplo:

{
  "equipamentos": [
    {
      "deviceId": "ABCD",
      "nome": "Módulo",
      "modelo": "MRQ10",
      "familia": "NDV2",
      "versao": "3.2.2",
      "ip": "192.168.1.20",
      "noProjeto": false,
      "modoAp": false,
      "podeAdicionar": true
    }
  ],
  "total": 1
}

Outros erros possíveis: 404, 409.

Procura equipamentos na rede local (botão de atualizar)

POST /v1/projects/{id}/rede/descobrir

Limpa a lista, reenvia o discovery e reconfirma os IPs conhecidos. Responde depois de cerca de 1 segundo com a lista; quem responder depois aparece em listar_equipamentos_na_rede. Não mexe nos equipamentos. Em VPN o multicast não passa: use localizar_equipamentos_por_ip. Convidado pode. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: descobrir_equipamentos_na_rede.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Exemplo:

{
  "multicastEnviado": true,
  "equipamentos": [],
  "total": 0
}

Outros erros possíveis: 404, 409, 422.

Procura equipamentos numa faixa de IPs (Localizar por IP)

POST /v1/projects/{id}/rede/localizar

Responde 202 com execucaoId; acompanhe em ver_execucao. Faz GET /if/device em cada endereço, 20 por vez, esperando até 4 segundos cada grupo. Os achados entram na lista da rede. É o caminho em VPN. A faixa precisa estar na rede de uma interface deste computador, com só o último número variando e até 254 endereços (422). Convidado pode. Janela “Localizar via IP” aberta ou outra localização em curso: 409. Função desligada: 403. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: localizar_equipamentos_por_ip.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
inicio	texto	sim	Primeiro IP.
fim	texto	sim	Último IP.

Exemplo:

{
  "inicio": "192.168.1.1",
  "fim": "192.168.1.254"
}

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Exemplo:

{
  "execucaoId": "9f3a1c02b7e64d10",
  "tipo": "localizar_por_ip",
  "estado": "em_andamento",
  "acompanhar": "/v1/projects/h1/execucoes/9f3a1c02b7e64d10"
}

Outros erros possíveis: 404, 409, 422.

Para uma localização por IP em andamento

POST /v1/projects/{id}/rede/localizar/{execucaoId}/parar

O “Parar”. Responde 202: as tentativas já iniciadas terminam primeiro, e ver_execucao mostra o fim, com parado verdadeiro e o que foi encontrado até ali. Já terminada: 409. Função desligada: 403. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: parar_localizacao_por_ip.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
execucaoId	caminho	sim	Id devolvido por localizar_equipamentos_por_ip.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Exemplo:

{
  "execucaoId": "9f3a1c02b7e64d10",
  "acompanhar": "/v1/projects/h1/execucoes/9f3a1c02b7e64d10"
}

Outros erros possíveis: 404, 409, 422.

JSON com cenas, configurações e nomes do equipamento (Exportar)

GET /v1/projects/{id}/devices/{deviceId}/exportar

O JSON do botão “Exportar”, no corpo, pronto para importar_equipamento. Lê a nuvem. Diferente do arquivo da tela, não traz /lb/wifi, parâmetros internos nem ações sem caminho (item vazio que equipamento legacy guarda), e campo de nome secreto numa ação fora de /ac/* sai como *** (o payload de /aa/* fica). Convidado pode. Função desligada: 403. Legacy offline: 409. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: exportar_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Id do equipamento (GET …/devices).

Resposta 200 (Sucesso)

Exemplo:

{
  "deviceId": "ABCD",
  "source": "database",
  "actionsConfig": {},
  "configs": {},
  "buttons": {}
}

Outros erros possíveis: 404, 409.

Substitui cenas, configurações e nomes do equipamento (Importar)

POST /v1/projects/{id}/devices/{deviceId}/importar

Corpo: o JSON de exportar_equipamento. Cada ação passa pela lista de permissão de importar_acoes_no_botao; parâmetro iniciado com _, /lb/wifi, troca de ID e config ou parâmetro que o equipamento não descreve dão 422. Responde 202 com execucaoId; acompanhe em ver_execucao. Substitui o que existe e envia ao equipamento; não pode ser desfeito. Sem conexão, fica gravado e pendente de envio. Falha de envio: erroDeEnvio no item que parou. JSON fora do formato: 422, nada gravado. /lb/wifi ou /lb/device.id de outro equipamento: 422, essas trocas ficam no Studio. Arquivo de outro equipamento: 409, a não ser com permitirOutroEquipamento=true. Só o dono. Função desligada: 403. Legacy offline ou outro envio em curso: 409. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: importar_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Id do equipamento (GET …/devices).
permitirOutroEquipamento	consulta	não	true confirma importar o arquivo de outro equipamento. Valores: true, false.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
source	texto	sim	Sempre “database”.
deviceId	texto	não	Equipamento de origem.
deviceName	texto	não	Nome do equipamento de origem (informativo).
model	texto	não	Modelo do equipamento de origem (informativo).
version	texto	não	Firmware do equipamento de origem (informativo).
exportedAt	texto	não	Quando o export foi feito (informativo).
actionsConfig	objeto	não
configs	objeto	não
buttons	objeto	não

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Exemplo:

{
  "execucaoId": "9f3a1c02b7e64d10",
  "tipo": "importar_equipamento",
  "estado": "em_andamento",
  "acompanhar": "/v1/projects/h1/execucoes/9f3a1c02b7e64d10"
}

Outros erros possíveis: 404, 409, 422.

Vinculação e uso do acesso externo (card da tela)

GET /v1/projects/{id}/devices/{deviceId}/acesso-externo

situacao: disponivel, ativo, regravado ou bloqueado. uso: comandos do dia anterior por origem, só com situacao ativo. Consulta o equipamento pela rede, por isso não vem em ver_equipamento; a resposta fica guardada enquanto continuar sendo consultada, até 2 minutos sem consulta. Firmware sem /if/ext (ou descrição ainda não carregada): 409. Precisa do projeto aberto (409).

Ferramenta MCP: ver_acesso_externo.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Id do equipamento (GET …/devices).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc",
  "situacao": "ativo",
  "comunicacaoExternaOnline": true,
  "uso": {
    "dia": "2026-10-29",
    "total": 3,
    "porOrigem": {
      "alexa": 3
    }
  },
  "motivoSemUso": null
}

Outros erros possíveis: 404, 409.

Vincula o equipamento ao acesso externo deste projeto (Vincular)

POST /v1/projects/{id}/devices/{deviceId}/acesso-externo/vincular

Pede o código ao equipamento pela rede local e o entrega ao serviço. Nunca troca de projeto: já vinculado em outro, ou sem como confirmar, é 409 e a vinculação deve ser feita manualmente no Studio. Só o dono. Função desligada: 403. Firmware sem suporte, offline, legacy offline, já vinculado, mesmo ID em uso ou recusa: 409. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: vincular_acesso_externo.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Id do equipamento (GET …/devices).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc",
  "vinculado": true,
  "mensagem": "Acesso externo habilitado."
}

Outros erros possíveis: 404, 409, 422.

Coleta cenas e configurações de um equipamento legacy

POST /v1/projects/{id}/devices/{deviceId}/exportacao

Pergunta ao próprio equipamento e devolve o JSON; não grava nada. Responde 202 com execucaoId; o resultado sai em ver_execucao e pode levar minutos. Sem /lb/wifi, sem parâmetro interno e com segredos mascarados. Caminho que não responde vai em falhas. Só legacy online: para os demais, use exportar_equipamento, que lê o banco. Função desligada: 403. Equipamento moderno, offline, sem descrição ou coleta já em curso: 409. Precisa do app instalado e do projeto aberto (409).

Ferramenta MCP: exportar_equipamento_legacy.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Id do equipamento (GET …/devices).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Exemplo:

{
  "execucaoId": "9f3a1c02b7e64d10",
  "tipo": "exportar_equipamento_legacy",
  "estado": "em_andamento",
  "acompanhar": "/v1/projects/abc/execucoes/9f3a1c02b7e64d10"
}

Outros erros possíveis: 404, 409.

Versões de firmware do equipamento (só consulta)

GET /v1/projects/{id}/devices/{deviceId}/firmware

Versão atual, versões oferecidas e versaoDisponivel (a mais nova estável; null se está em dia), sempre do modelo e do tipo do equipamento. Só consulta: atualizar, forçar e migrar ficam na tela do Studio. Só o dono. Função desligada: 403. Sem rede local ou sem internet: 409.

Ferramenta MCP: ver_firmware_do_equipamento.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Id do equipamento (GET …/devices).
beta	consulta	não	true inclui as versões beta na lista. Sem ele, nunca. Valores: true, false.
anteriores	consulta	não	true inclui versões mais antigas que a atual. Valores: true, false.

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "devK",
  "modelo": "MRQ10",
  "tipo": "NDV2",
  "familia": "moderna",
  "versaoAtual": "3.2.2",
  "versaoAtualEhBeta": false,
  "versaoDisponivel": "3.3.0",
  "incluiBeta": false,
  "incluiAnteriores": false,
  "versoes": [
    {
      "versao": "3.3.0",
      "tipo": "NDV2",
      "beta": false,
      "atual": false,
      "data": "2026-10-01T00:00:00.000",
      "notas": ""
    }
  ],
  "mensagem": "Atualizar, forçar e migrar firmware ficam só na tela do Studio SHC: uma falha pode deixar o equipamento inoperante e exigir gravação no local. A API local só consulta as versões."
}

Outros erros possíveis: 404, 409, 422.

Ambientes

Lista os ambientes

GET /v1/projects/{id}/rooms

Ambientes com a contagem de entradas e saídas.

Ferramenta MCP: listar_ambientes.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
ambientes	lista	id, nome, totalDeEntradas, totalDeSaidas.
total	inteiro

Outros erros possíveis: 404.

Cria um ambiente

POST /v1/projects/{id}/rooms

Só o dono do projeto.

Ferramenta MCP: criar_ambiente.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
nome	texto	sim	Nome novo, não vazio.

Exemplo:

{
  "nome": "Quarto"
}

Resposta 201 (Criado)

Exemplo:

{
  "id": "r1",
  "nome": "Quarto",
  "totalDeEntradas": 0,
  "totalDeSaidas": 0
}

Outros erros possíveis: 404, 422.

Mostra um ambiente

GET /v1/projects/{id}/rooms/{roomId}

Ambiente com as entradas e saídas dele.

Ferramenta MCP: ver_ambiente.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
roomId	caminho	sim	Id do ambiente.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Renomeia um ambiente

PATCH /v1/projects/{id}/rooms/{roomId}

Só o dono do projeto.

Ferramenta MCP: renomear_ambiente.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
roomId	caminho	sim	Id do ambiente.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
nome	texto	sim	Nome novo, não vazio.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	Id.
nome	texto	Nome.

Outros erros possíveis: 404, 422.

Exclui um ambiente

DELETE /v1/projects/{id}/rooms/{roomId}

Como o “Excluir ambiente”: o que estava nele fica sem ambiente. Só o dono.

Ferramenta MCP: excluir_ambiente.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
roomId	caminho	sim	Id do ambiente.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
id	texto	Id.
removido	true ou false

Outros erros possíveis: 404.

Define o fundo (imagem ou cor) do ambiente

PUT /v1/projects/{id}/rooms/{roomId}/fundo

Como o formulário do ambiente: uma cor da paleta ({“cor”: “#FFB3BA”}) ou uma imagem PNG/JPEG em base64, até 512 KiB, que vai ao Storage ({“imagem”: {“base64”, “tipo”}}). A tela reduz a imagem para 800×800; a API não redimensiona — envie pronta. Tirar o fundo não é possível (a tela também não faz). Só o dono.

Ferramenta MCP: definir_fundo_do_ambiente.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
roomId	caminho	sim	Id do ambiente.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
cor	texto	não	Cor da paleta (#RRGGBB).
imagem	objeto	não
imagem.base64	texto	sim	Bytes da imagem em base64, sem “data:”.
imagem.tipo	image/png, image/jpeg	sim	Tipo.

Exemplo:

{
  "cor": "#BAE1FF"
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Entradas (botões)

Lista as entradas (botões)

GET /v1/projects/{id}/inputs

Botões do projeto, como a tab Entradas. O id de cada um é o inputId das cenas. nome: o nome mostrado (o que o usuário deu, ou o do equipamento). nomeAmigavel: o nome que o próprio equipamento descreve; null quando ele não descreve, e não muda ao renomear.

Ferramenta MCP: listar_entradas.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
equipamentoId	consulta	não	Só deste equipamento (docId).
ambienteId	consulta	não	Só deste ambiente.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
entradas	lista	id, equipamentoId, nome, nomeAmigavel, path, ambienteId, pendenciasDeEnvio.
total	inteiro

Outros erros possíveis: 404.

Mostra uma entrada

GET /v1/projects/{id}/inputs/{inputId}

Um botão.

Ferramenta MCP: ver_entrada.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Muda o nome e/ou o ambiente de uma entrada

PATCH /v1/projects/{id}/inputs/{inputId}

Só o dono do projeto. O nome novo volta em nome (nomeAmigavel é o do equipamento e não muda). Em teclados com botões fisicamente juntos (ex.: KEYPADWIFI, botões 1 a 8), o ambiente vale para todos eles: mudar o de um muda o de todos, de propósito. A resposta lista os outros em entradasQueMudaramJunto, com um aviso.

Ferramenta MCP: alterar_entrada.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Mande pelo menos 1 campo: o corpo vazio é recusado.

Campo	Tipo	Obrigatório	Para que serve
nome	texto	não	Nome novo, não vazio.
ambienteId	texto ou null	não	Id de um ambiente do projeto (GET …/rooms), ou null para tirar do ambiente.

Exemplo:

{
  "nome": "Luz da Sala",
  "ambienteId": "sala"
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 422.

Saídas

Lista as saídas

GET /v1/projects/{id}/outputs

estadoAtual: último valor visto na rede; null = nunca visto, não quer dizer desligada. estadoDisponivel false: projeto fechado no Studio. Saídas do projeto e os comandos dos aparelhos de preset, como a tab Saídas. O id é o saidaId das ações de botão. nome: o nome mostrado (o que o usuário deu, ou o do equipamento). nomeAmigavel: o nome que o próprio equipamento descreve; null quando ele não descreve, e não muda ao renomear.

Ferramenta MCP: listar_saidas.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
equipamentoId	consulta	não	Só deste equipamento (docId).
ambienteId	consulta	não	Só deste ambiente.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
saidas	lista	id, equipamentoId, nome, path, parametro, valores, limites, ambienteId, oculta, agrupada, comandoDePreset.
total	inteiro

Outros erros possíveis: 404.

Mostra uma saída

GET /v1/projects/{id}/outputs/{outputId}

estadoAtual: último valor visto na rede; null = nunca visto, não quer dizer desligada. estadoDisponivel false: projeto fechado no Studio. Uma saída.

Ferramenta MCP: ver_saida.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
outputId	caminho	sim	Id da saída.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Muda nome, ambiente, ícone, oculta e categoria de uma saída

PATCH /v1/projects/{id}/outputs/{outputId}

Só o dono. Saída agrupada (zona, persiana): tudo é do GRUPO inteiro — nas zonas o nome também vai ao display do equipamento (nomeEnviadoAoDisplay). icone: um de iconesDisponiveis. oculta: a saída some da tab e da busca dos botões. categoria: o “Grupo” da tela, um de categoriasDisponiveis ou null; acento e maiúscula não importam, e grava na grafia de categoriasDisponiveis: as da lista oficial com acento (Climatização, mesmo que o equipamento descreva Climatizacao), as demais como o equipamento descreve. O nome novo volta em nome (nomeAmigavel é o do equipamento e não muda). Comando de preset não tem nome próprio nem estes ajustes (422). oculta e categoria são a aba Configurações da linha: com o projeto fechado no Studio, divergência ou legacy offline no equipamento da saída dão 409, com o motivo e o que fazer.

Ferramenta MCP: alterar_saida.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
outputId	caminho	sim	Id da saída.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Mande pelo menos 1 campo: o corpo vazio é recusado.

Campo	Tipo	Obrigatório	Para que serve
nome	texto	não	Nome novo, não vazio.
ambienteId	texto ou null	não	Id de um ambiente do projeto, ou null para tirar.
icone	texto	não	Um de iconesDisponiveis (GET da saída).
oculta	true ou false	não
categoria	texto ou null	não	Um de categoriasDisponiveis (GET da saída), com ou sem acento, ou null.

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Botões que controlam uma saída (Controlado por)

GET /v1/projects/{id}/outputs/{outputId}/controladores

A lista da aba “Controlado por”, sem varrer as cenas. Saída agrupada traz o grupo inteiro. Ação de preset vem pelo nome do comando, sem o valor cru; presetAusente: o preset não está no projeto. Convidado pode.

Ferramenta MCP: ver_controladores_da_saida.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
outputId	caminho	sim	Id da saída (GET …/outputs).

Resposta 200 (Sucesso)

Exemplo:

{
  "controladores": [
    {
      "entradaId": "devK-_cs_bt0",
      "botao": "Botão 1",
      "equipamentoId": "devK",
      "equipamento": "Keypad",
      "ambiente": "Sala",
      "gesto": "clique",
      "n": 0,
      "parametro": "r0",
      "valor": "toggle",
      "inverterAoDesligar": "",
      "presetAusente": false,
      "comandoDePreset": null
    }
  ],
  "total": 1
}

Outros erros possíveis: 404.

Tira um botão do controle da saída (Remover associação)

DELETE /v1/projects/{id}/outputs/{outputId}/controladores/{inputId}

Tira o parâmetro da ação; se era o único, a ação. Comando de preset sai inteiro. Só muda o projeto: o equipamento recebe ao sincronizar. Botão em mais de uma ação da saída: 422, informe n e, em grupo, parametro. Só o dono. Projeto fechado, divergência ou legacy offline (no botão ou na saída): 409.

Ferramenta MCP: remover_controlador_da_saida.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
outputId	caminho	sim	Id da saída (GET …/outputs).
inputId	caminho	sim	entradaId da lista de controladores.
n	consulta	não	O n da lista, quando há mais de uma ação.
parametro	consulta	não	O parametro da lista, quando há mais de um.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Exemplo:

{
  "removida": true,
  "n": 0,
  "parametro": "r0",
  "comandoDePresetInteiro": false,
  "pendenciasDeEnvio": 1
}

Outros erros possíveis: 404, 409, 422.

Ações dos botões

Resumo das ações de cada botão

GET /v1/projects/{id}/scenes

Um item por botão, sem ler as ações: id, nome, equipamento, path e pendências de envio. As posições usadas (capacidade, máximo 30 por botão) vêm em GET …/scenes/{inputId}/acoes.

Ferramenta MCP: listar_cenas.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
cenas	lista	id (= inputId), entradaId, nome, equipamentoId, path, pendenciasDeEnvio.
total	inteiro

Outros erros possíveis: 404.

Ações de clique e de segurar de um botão

GET /v1/projects/{id}/scenes/{inputId}

Igual a GET …/scenes/{inputId}/acoes.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Ações de clique e de segurar de um botão

GET /v1/projects/{id}/scenes/{inputId}/acoes

O que o botão faz: listas clique (n = 0, 1, 2…) e segurar (n = -1, -2…), cada ação com a saída, os valores e a inversão. Com formato=copiar: o JSON do “Copiar” da tela, de um gesto, pronto para o corpo de importar_acoes_no_botao; só o dono.

Ferramenta MCP: ver_acoes_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
formato	consulta	não	copiar: o formato do botão Copiar. Valores: copiar.
gesto	consulta	não	Com formato=copiar, o gesto copiado (padrão clique). Valores: clique, segurar.

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
clique	lista
segurar	lista
capacidade	objeto
pendenciasDeEnvio	inteiro

Outros erros possíveis: 404.

Adiciona ações a um botão

POST /v1/projects/{id}/scenes/{inputId}/acoes

Como a tab Entradas: junta na ação existente quando é o mesmo equipamento, o mesmo path e a mesma inversão sem parâmetro repetido; senão ocupa uma posição nova (máximo 30 por botão). Comando de preset passa pelas mesmas recusas da tela. Saída oculta ou desligada na configuração do equipamento não é oferecida (422). Só o dono; projeto fechado no Studio, equipamento legacy offline ou com diferença na nuvem dá 409, e ação avançada (/aa) também (fica na tela). A gravação vai para o projeto; o equipamento só recebe quando o Studio sincroniza (pendenciasDeEnvio na resposta).

Ferramenta MCP: adicionar_acoes_ao_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
gesto	clique, segurar	sim	Gesto.
desligarAoSoltar	on, off, "" (vazio)	não	Só no gesto segurar: on, off ou “” (nada).
acoes	lista (mín. 1 item)	sim
acoes[].saidaId	texto	sim	Id da saída (GET …/outputs).
acoes[].valor	texto	não	Valor (ex.: “on”, “50”); sem ele, o padrão da saída.
acoes[].inverterAoDesligar	on, off	não	on ou off (padrão).

Exemplo:

{
  "gesto": "clique",
  "acoes": [
    {
      "saidaId": "devR-_ac_rs-r0",
      "valor": "on"
    }
  ]
}

Resposta 201 (Criado)

Outros erros possíveis: 404, 409, 422.

Mostra uma ação do botão

GET /v1/projects/{id}/scenes/{inputId}/acoes/{n}

n é a posição: 0, 1, 2… no clique; -1, -2… no segurar.

Ferramenta MCP: ver_acao_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
n	caminho	sim	Posição da ação.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Muda os valores de uma ação do botão

PATCH /v1/projects/{id}/scenes/{inputId}/acoes/{n}

Como o lápis da linha: só os parâmetros que a ação já tem e a inversão — inverterAoDesligar para a ação inteira, ou inverterPorParametro com uma inversão por parâmetro; inversões diferentes dividem a ação em uma por inversão, no lugar dela (as seguintes mudam de número). Ação de preset com aparelho no projeto não se edita (o aparelho manda; 422). Só o dono. Projeto fechado no Studio, divergência, legacy offline, ação avançada (/aa) ou ação gravada fora da lista de permissão: 409. A gravação vai para o projeto; o equipamento só recebe quando o Studio sincroniza (pendenciasDeEnvio na resposta).

Ferramenta MCP: editar_acao_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
n	caminho	sim	Posição da ação.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Mande pelo menos 1 campo: o corpo vazio é recusado.

Campo	Tipo	Obrigatório	Para que serve
valores	objeto	não	Parâmetro → valor (ex.: {“r0”: “on”}).
inverterAoDesligar	on, off	não	on ou off.
inverterPorParametro	objeto	não	Parâmetro → on/off (os ausentes mantêm a inversão atual). Não use junto com inverterAoDesligar.

Exemplo:

{
  "valores": {
    "r0": "off"
  }
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Apaga uma ação do botão

DELETE /v1/projects/{id}/scenes/{inputId}/acoes/{n}

Apaga e renumera o gesto (as posições continuam seguidas). Só o dono; projeto fechado no Studio, divergência ou legacy offline: 409. A gravação vai para o projeto; o equipamento só recebe quando o Studio sincroniza (pendenciasDeEnvio na resposta).

Ferramenta MCP: excluir_acao_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
n	caminho	sim	Posição da ação.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409.

Recarrega as ações do botão a partir do equipamento

POST /v1/projects/{id}/scenes/{inputId}/recarregar

O “Recarregar” da tab Entradas: pede ao equipamento as ações do botão e grava no projeto (a pendência do botão some). Moderno traz clique e segurar; legacy só o gesto pedido. Precisa do app instalado e do equipamento online (409). Resposta incompleta não grava nada (409, tente de novo). Só o dono; projeto fechado no Studio, equipamento com diferença na nuvem ou legacy offline dá 409.

Ferramenta MCP: recarregar_acoes_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
gesto	clique, segurar	não	Gesto.

Resposta 200 (Sucesso)

Exemplo:

{
  "acoes": 2,
  "gravou": true,
  "caminho": "getAll",
  "mensagem": "2 cena(s) recarregada(s)."
}

Outros erros possíveis: 404, 409, 422.

Apaga todas as ações do botão

POST /v1/projects/{id}/scenes/{inputId}/resetar

O “Reset” da tab Entradas: apaga clique e segurar no projeto. O equipamento só recebe quando o Studio sincroniza (pendenciasDeEnvio na resposta). Só o dono; projeto fechado no Studio, equipamento com diferença na nuvem ou legacy offline dá 409.

Ferramenta MCP: resetar_acoes_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Substitui as ações de um gesto (o “Colar”)

POST /v1/projects/{id}/scenes/{inputId}/importar

O “Colar” da tab Entradas: troca TODAS as ações do gesto pelas de items, no formato do “Copiar” (path, id, host, query, invertToOff, offOnRelease), renumeradas a partir de 0 (clique) ou -1 (segurar). Recusa passar de 30 ações no botão. Lista de permissão: só /ac/, e /aa/ igual ao que um comando de preset de um aparelho do projeto gera (volta como comando); o resto (/lb, /if, /cf, /cs, /cl, /ota…) e parâmetro iniciado com _ dão 422, com o motivo por ação. O equipamento só recebe quando o Studio sincroniza (pendenciasDeEnvio na resposta). Só o dono; projeto fechado no Studio, equipamento com diferença na nuvem ou legacy offline dá 409.

Ferramenta MCP: importar_acoes_no_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
gesto	clique, segurar	sim	Gesto.
isHold	true ou false	não	Do JSON do “Copiar”; aceito e ignorado (vale gesto).
items	lista (mín. 1 item)	sim
items[]._n	inteiro	não	Ignorado.
items[].path	texto	sim	Path da ação (ex.: /ac/rs).
items[].id	texto	sim	deviceId (4 hex) do equipamento alvo.
items[].host	texto	não	IP do alvo (opcional).
items[].query	texto	não	Parâmetros (ex.: r0=on;r1=off).
items[].invertToOff	texto	não	on, off ou “”.
items[].offOnRelease	texto	não	on, off ou “”.

Exemplo:

{
  "gesto": "clique",
  "items": [
    {
      "path": "/ac/rs",
      "id": "6A6F",
      "query": "r0=on"
    }
  ]
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Mostra o agendamento do botão

GET /v1/projects/{id}/scenes/{inputId}/agendamento

O agendamento (cron) do botão: ativo, hora, minuto e dias. Só equipamentos que descrevem cronEnable têm (409 nos demais).

Ferramenta MCP: ver_agendamento_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).

Resposta 200 (Sucesso)

Campo	Tipo	O que traz
ativo	true ou false
hora	inteiro
minuto	inteiro
dias	lista de dom, seg, ter, qua, qui, sex, sab
pendenciasDeEnvio	inteiro

Outros erros possíveis: 404, 409.

Altera o agendamento do botão

PATCH /v1/projects/{id}/scenes/{inputId}/agendamento

Como o switch e o card Agendamento da linha do botão: muda só o que vier. Ligar sem dias escolhe todos; ligado com “dias”: [] é 422. O equipamento só recebe quando o Studio sincroniza (pendenciasDeEnvio na resposta). Só o dono; projeto fechado no Studio, equipamento com diferença na nuvem ou legacy offline dá 409.

Ferramenta MCP: alterar_agendamento_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Mande pelo menos 1 campo: o corpo vazio é recusado.

Campo	Tipo	Obrigatório	Para que serve
ativo	true ou false	não
hora	inteiro (mín. 0, máx. 23)	não
minuto	inteiro (mín. 0, máx. 59)	não
dias	lista de dom, seg, ter, qua, qui, sex, sab	não

Exemplo:

{
  "ativo": true,
  "hora": 18,
  "minuto": 30,
  "dias": [
    "seg",
    "qua",
    "sex"
  ]
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Envio aos equipamentos

Pendências de envio aos equipamentos

GET /v1/projects/{id}/sincronizar

O “(N)” e a lista do “Atualizar tudo”: total de alterações de cena, configuração e agendamento ainda não enviadas, quantos equipamentos receberiam agora e o estado de cada um, com os itens que vão (caminho, tipo cena, configuracao ou agendamento, nome). Ação já gravada fora do que a API aceita, num botão com pendência, vem em acoesForaDaLista, com aviso; não bloqueia o envio. Projeto fechado no Studio dá 409 (use abrir_projeto).

Ferramenta MCP: ver_pendencias_de_envio.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Exemplo:

{
  "total": 3,
  "prontos": 1,
  "equipamentos": [
    {
      "id": "abc",
      "nome": "Módulo",
      "pendencias": 3,
      "pronto": true,
      "online": true,
      "tcpConectado": false,
      "viaAcessoExterno": false
    }
  ]
}

Outros erros possíveis: 404, 409.

Envia as pendências aos equipamentos (Atualizar tudo)

POST /v1/projects/{id}/sincronizar

Responde 202 com execucaoId; acompanhe em ver_execucao. Só os equipamentos prontos recebem; o resultado lista os demais em naoEnviados. ACK seguido de queda do TCP conta como falha. Só o dono, com o app instalado e o projeto aberto. Sem nenhuma pendência, janela “Atualizar devices” aberta ou outro envio em curso dá 409.

Ferramenta MCP: sincronizar_projeto.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Exemplo:

{
  "execucaoId": "9f3a1c02b7e64d10",
  "tipo": "sincronizar",
  "estado": "em_andamento",
  "acompanhar": "/v1/projects/h1/execucoes/9f3a1c02b7e64d10"
}

Outros erros possíveis: 404, 409, 422.

Acompanha um trabalho em segundo plano (resposta 202)

GET /v1/projects/{id}/execucoes/{execucaoId}

Serve a todo POST que respondeu 202 com execucaoId: envio, resolução de divergência, importação, coleta legacy e localização por IP. estado: em_andamento, concluida ou falhou. Em andamento, o envio traz progresso por equipamento e a localização por IP, total, testados e encontrados; ao terminar, resultado. Execuções ficam na memória: somem ao fechar o Studio (404).

Ferramenta MCP: ver_execucao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
execucaoId	caminho	sim	Id devolvido pelo POST que iniciou o trabalho.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Comandos

Qual botão foi pressionado por último

GET /v1/projects/{id}/inputs/ultimo-pressionado

Serve para pedir “aperte o botão” e descobrir qual foi: guarde o campo agora, peça o aperto e consulte com desde. pressionado null: nada desde então. Conta tecla física e o play do Studio. Projeto fechado ou sem rede local dá 409.

Ferramenta MCP: ver_ultimo_botao_pressionado.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
desde	consulta	não	Só pressionamentos depois deste instante (ISO 8601).

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Aciona uma saída agora (liga, desliga, ajusta)

POST /v1/projects/{id}/outputs/{outputId}/acionar

Move carga real: confirme com a pessoa antes de acionar persiana ou o que puder surpreender. Sem valor, é o clique do ícone: inverte a saída (grupo: o power da zona ou o parar/alternar da persiana). Com valor, vai para o parâmetro desta saída, conferido pelo tipo e pelos limites (tipoDoParametro, valores e limites em ver_saida). Não grava nada. Convidado pode. Comando de preset: use executar_comando (409). Ação avançada (/aa) fica só na tela (409). Sem valor numa saída sem liga/desliga: 409. Precisa do app instalado, projeto aberto e equipamento online (409). Equipamento que não confirmou: 409 (o comando pode ter chegado).

Ferramenta MCP: acionar_saida.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
outputId	caminho	sim	Id da saída (GET …/outputs).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
valor	texto ou número	não	on, off, toggle, número ou opção da saída.

Exemplo:

{
  "valor": "on"
}

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "abc-_ac_rs-r4",
  "path": "/ac/rs",
  "parametro": "r4",
  "valorEnviado": "on",
  "confirmado": true,
  "estadoAtual": "on"
}

Outros erros possíveis: 404, 409, 422.

Executa as ações de um botão, como apertar a tecla

POST /v1/projects/{id}/inputs/{inputId}/executar

O play da tab Entradas: o equipamento roda as ações gravadas NELE (o que ainda não foi sincronizado não vale). Move carga real e um clique pode mexer em várias saídas: veja antes com ver_acoes_do_botao. Equipamento sem /cl/actions (hasSceneActions falso) dá 409: use simular_acoes_do_botao. Convidado pode. Precisa do app instalado, projeto aberto e equipamento online (409). Equipamento legacy com gesto segurar executa o clique e a resposta traz aviso.

Ferramenta MCP: executar_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
gesto	clique, segurar	não	Padrão: clique.

Exemplo:

{
  "gesto": "clique"
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Simula as ações do botão (Acender/Apagar)

POST /v1/projects/{id}/scenes/{inputId}/simular

Cada ação vai direto ao alvo, sem gravar: as do projeto, mesmo ainda não sincronizadas. toggle vira on; inverter true apaga (o equipamento inverte os valores). Move carga real. Resposta por ação. Só vai ao equipamento o que está na lista de permissão: /ac/* e comando de preset de um aparelho do projeto; o resto, mesmo já gravado, volta com recusada: true e o motivo em erro, e o que está na lista segue. Parâmetro iniciado com _ não vai no pacote. Convidado pode. Equipamento com divergência, legacy offline, projeto fechado, sem rede local ou gesto sem ações dá 409.

Ferramenta MCP: simular_acoes_do_botao.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
gesto	clique, segurar	não	Padrão: clique.
inverter	true ou false	não	true = Apagar.

Exemplo:

{
  "gesto": "clique",
  "inverter": false
}

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Aparelhos de preset

Vê se há versão nova do preset (só leitura)

GET /v1/projects/{id}/devices/{deviceId}/atualizacao

Versão, o que mudou, botões que usam, editados à mão e campos que faltam. Aplicar fica só no Studio: não existe rota para isso. Projeto fechado no Studio dá 409.

Ferramenta MCP: ver_atualizacao_do_aparelho.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Aparelho de preset: preset:{aparelhoId}.

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409.

Botões que usam os comandos do aparelho

GET /v1/projects/{id}/devices/{deviceId}/usos

Quem perde ação se o aparelho sair. Projeto fechado no Studio dá 409.

Ferramenta MCP: ver_usos_do_aparelho.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Aparelho de preset: preset:{aparelhoId}.

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409.

Pareia o aparelho (alguém aceita na tela dele)

POST /v1/projects/{id}/devices/{deviceId}/parear

Responde 202 na hora; acompanhe em ver_pareamento_do_aparelho. Avise a pessoa: o aparelho mostra Permitir na tela e a espera pode passar de 30 s. Repetir devolve o pedido em andamento sem pedir Permitir de novo. Sem comandoId, pede só os canais sem token. Com comandoId (o comando de tokenRecusado, ou o de pareamento), refaz só aquele canal, mesmo com token salvo. Já pareado e sem comandoId: 409 (para começar de novo, desparear_aparelho). Aparelho sem pareamento: 409. Só o dono, com o app instalado (no navegador, 409). Login pelo navegador é só no Studio (409). O token nunca aparece na resposta.

Ferramenta MCP: parear_aparelho.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Aparelho de preset: preset:{aparelhoId}.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
comandoId	texto	não	Canal a refazer.

Exemplo:

{
  "comandoId": "ligar"
}

Resposta 202 (Aceito: o trabalho continua em segundo plano)

Exemplo:

{
  "id": "preset:v1",
  "situacao": "aguardando",
  "erro": null,
  "camposPareados": [],
  "canaisPendentes": [
    {
      "id": "parear",
      "nome": "Parear"
    }
  ],
  "jaEmAndamento": false,
  "acompanhar": "/v1/projects/h1/devices/preset:v1/pareamento"
}

Outros erros possíveis: 404, 409, 422.

Situação do pareamento

GET /v1/projects/{id}/devices/{deviceId}/pareamento

situacao: aguardando, pareado, falhou, naoPareado ou semPareamento; erro; canaisPendentes; camposPareados só com os nomes. O resultado do último pedido fica guardado na memória até o Studio fechar ou a API local ser desligada; desparear o apaga.

Ferramenta MCP: ver_pareamento_do_aparelho.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Aparelho de preset: preset:{aparelhoId}.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Desfaz o pareamento (apaga o token salvo)

DELETE /v1/projects/{id}/devices/{deviceId}/pareamento

O Desparear da tela: os comandos param até parear de novo. A autorização continua na lista do próprio aparelho. Só o dono; aparelho não pareado dá 409.

Ferramenta MCP: desparear_aparelho.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Aparelho de preset: preset:{aparelhoId}.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409.

Pergunta o estado ao aparelho agora

GET /v1/projects/{id}/devices/{deviceId}/estado

Roda o comando de leitura do preset e devolve lidos. VAI À REDE a cada chamada e pode gravar um token renovado. Preset sem leitura dá 409; sem pareamento, responde pareado false com a frase da tela. Token recusado volta em tokenRecusado: chame parear_aparelho. Exige acesso à aba Saídas ou Dispositivos e o app instalado (no navegador, 409).

Ferramenta MCP: ler_estado_do_aparelho.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
deviceId	caminho	sim	Aparelho de preset: preset:{aparelhoId}.

Resposta 200 (Sucesso)

Exemplo:

{
  "ok": true,
  "pareado": true,
  "erro": null,
  "tokenRecusado": false,
  "lidos": [
    {
      "rotulo": "Volume",
      "valor": "12"
    }
  ]
}

Outros erros possíveis: 404, 409.

Dispensa o aviso de comando removido do botão

DELETE /v1/projects/{id}/scenes/{inputId}/comandos-removidos/{removidoId}

O Dispensar da linha vermelha. O comando continua fora do botão; some só o aviso. removidoId vem de comandosRemovidos em ver_acoes_do_botao. Só o dono, com acesso à aba Entradas.

Ferramenta MCP: dispensar_aviso_de_comando_removido.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
inputId	caminho	sim	Id da entrada (botão).
removidoId	caminho	sim	id do item de comandosRemovidos.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Cenas do App

Lista as Cenas do App

GET /v1/projects/{id}/cenas-do-app

As cenas da tab Cenas do App, com cada ação, saída e valor. Não confunda com as ações de um botão (ver_acoes_do_botao).

Ferramenta MCP: listar_cenas_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Cria uma Cena do App

POST /v1/projects/{id}/cenas-do-app

Nome obrigatório; ações e emoji são opcionais, como na tela (se vier, acoes não pode ser lista vazia: 422). Quem recebeu o projeto compartilhado também pode criar.

Ferramenta MCP: criar_cena_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
nome	texto	sim	Nome da cena.
emoji	texto	não	Emoji da cena.
acoes	lista	não	Ações a adicionar.
acoes[].saidaId	texto	sim	Id da saída (GET …/outputs).
acoes[].valor	texto ou número	não	on, off, número ou opção; obrigatório (422 sem ele), exceto em comando de preset, onde é ignorado. toggle não existe em cena do app.
aoConflitar	substituir, manterOsDois	não	Quando a saída já está na cena com outro valor: substituir, ou manterOsDois (a saída muda duas vezes). Sem isto, conflito dá 409 e nada é gravado.

Exemplo:

{
  "nome": "Saída à noite",
  "emoji": "🌙",
  "acoes": [
    {
      "saidaId": "abc-_ac_rs-r4",
      "valor": "off"
    }
  ]
}

Resposta 201 (Criado)

Outros erros possíveis: 404, 409, 422.

Vê uma Cena do App

GET /v1/projects/{id}/cenas-do-app/{cenaId}

Ações, saídas, valores e se você pode alterá-la.

Ferramenta MCP: ver_cena_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
cenaId	caminho	sim	Id da cena do app.

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Muda nome e emoji da Cena do App

PATCH /v1/projects/{id}/cenas-do-app/{cenaId}

emoji null tira o emoji. Só quem criou a cena ou o dono do projeto (403).

Ferramenta MCP: alterar_cena_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
cenaId	caminho	sim	Id da cena do app.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Mande pelo menos 1 campo: o corpo vazio é recusado.

Campo	Tipo	Obrigatório	Para que serve
nome	texto	não	Nome novo.
emoji	texto ou null	não	Emoji novo, ou null.

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 422.

Exclui a Cena do App

DELETE /v1/projects/{id}/cenas-do-app/{cenaId}

Apaga a cena. Só quem criou a cena ou o dono do projeto (403).

Ferramenta MCP: excluir_cena_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
cenaId	caminho	sim	Id da cena do app.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Adiciona ações à Cena do App

POST /v1/projects/{id}/cenas-do-app/{cenaId}/acoes

Mesma regra da tela: mesma saída e valor é duplicada (não muda nada); outra saída do mesmo equipamento e caminho entra na mesma ação; mesma saída com outro valor é conflito, e pede aoConflitar. Tudo ou nada. Só quem criou a cena ou o dono do projeto (403).

Ferramenta MCP: adicionar_acoes_a_cena_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
cenaId	caminho	sim	Id da cena do app.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, obrigatório)

Campo	Tipo	Obrigatório	Para que serve
acoes	lista	sim	Ações a adicionar.
acoes[].saidaId	texto	sim	Id da saída (GET …/outputs).
acoes[].valor	texto ou número	não	on, off, número ou opção; obrigatório (422 sem ele), exceto em comando de preset, onde é ignorado. toggle não existe em cena do app.
aoConflitar	substituir, manterOsDois	não	Quando a saída já está na cena com outro valor: substituir, ou manterOsDois (a saída muda duas vezes). Sem isto, conflito dá 409 e nada é gravado.

Resposta 200 (Sucesso)

Outros erros possíveis: 404, 409, 422.

Remove uma ação da Cena do App

DELETE /v1/projects/{id}/cenas-do-app/{cenaId}/acoes/{acaoId}

Sem parametro, a ação inteira (pode ter várias saídas); com parametro, só aquela saída. Só quem criou a cena ou o dono do projeto (403).

Ferramenta MCP: remover_acao_da_cena_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
cenaId	caminho	sim	Id da cena do app.
acaoId	caminho	sim	id da ação (ver_cena_do_app).
parametro	consulta	não	Remove só esta saída (ex.: r4).
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Resposta 200 (Sucesso)

Outros erros possíveis: 404.

Executa a Cena do App agora

POST /v1/projects/{id}/cenas-do-app/{cenaId}/executar

O play do card. Move carga real: veja antes com ver_cena_do_app. inverter true apaga (o equipamento inverte os valores) e pula comandos de preset, que não têm inverso. Não confere se o equipamento está online: quem não respondeu aparece por ação, e a espera pode chegar a uns 20 s (as ações vão em paralelo). Convidado pode. Precisa do app instalado e do projeto aberto (409); cena desabilitada também dá 409.

Ferramenta MCP: executar_cena_do_app.

Parâmetros

Nome	Onde	Obrigatório	Para que serve
id	caminho	sim	Id do projeto (GET /v1/projects).
cenaId	caminho	sim	Id da cena do app.
Idempotency-Key	cabeçalho	não	Repetir a escrita com a mesma chave devolve a mesma resposta sem executar de novo (1 h).

Corpo (JSON, opcional)

Campo	Tipo	Obrigatório	Para que serve
inverter	true ou false	não	true = apagar.

Exemplo:

{
  "inverter": false
}

Resposta 200 (Sucesso)

Exemplo:

{
  "id": "c1",
  "inverter": false,
  "total": 1,
  "confirmadas": 1,
  "mensagem": "1 ação enviada.",
  "acoes": [
    {
      "id": "a1",
      "equipamentoId": "abc",
      "path": "/ac/rs",
      "comandoDePreset": false,
      "confirmada": true
    }
  ]
}

Outros erros possíveis: 404, 409, 422.

O que a API recusa

Estes pedidos respondem 405 com o motivo na mensagem. Faça essas tarefas na tela do Studio SHC.

Método	Endereço	Motivo
DELETE	/v1/projects/{id}	Excluir o projeto fica só na tela Projeto do Studio SHC (ação crítica).
POST	/v1/projects/{id}/rooms/{roomId}	Para criar um ambiente, use POST /v1/projects/{id}/rooms.
POST	/v1/projects/{id}/inputs	As entradas vêm da descrição do equipamento.
POST	/v1/projects/{id}/inputs/{inputId}	As entradas vêm da descrição do equipamento; só nome e ambiente mudam.
DELETE	/v1/projects/{id}/inputs/{inputId}	As entradas vêm da descrição do equipamento; só nome e ambiente mudam.
POST	/v1/projects/{id}/outputs	As saídas vêm da descrição do equipamento.
POST	/v1/projects/{id}/outputs/{outputId}	As saídas vêm da descrição do equipamento; só nome, ambiente, ícone, oculta e categoria mudam.
DELETE	/v1/projects/{id}/outputs/{outputId}	As saídas vêm da descrição do equipamento; só nome, ambiente, ícone, oculta e categoria mudam.
POST	/v1/projects/{id}/scenes	A cena nasce com o botão; use POST …/scenes/{inputId}/acoes.
POST	/v1/projects/{id}/scenes/{inputId}	A cena é a lista de ações do botão; use …/acoes e …/acoes/{n}.
PATCH	/v1/projects/{id}/scenes/{inputId}	A cena é a lista de ações do botão; use …/acoes e …/acoes/{n}.
DELETE	/v1/projects/{id}/scenes/{inputId}	A cena é a lista de ações do botão; use …/acoes e …/acoes/{n}.
PATCH	/v1/projects/{id}/scenes/{inputId}/acoes	Altere ou apague uma ação por vez, em …/acoes/{n}.
DELETE	/v1/projects/{id}/scenes/{inputId}/acoes	Altere ou apague uma ação por vez, em …/acoes/{n}.
POST	/v1/projects/{id}/scenes/{inputId}/acoes/{n}	Para adicionar, use POST …/acoes.
DELETE	/v1/projects/{id}/planta	Apagar a planta fica só na tab Visual do Studio SHC, por ser uma ação sem volta; a API local não apaga plantas.
POST	/v1/projects/{id}/devices/{deviceId}/firmware	Atualizar, forçar e migrar firmware ficam só na tela do Studio SHC: uma falha pode deixar o equipamento inoperante e exigir gravação no local. A API local só consulta as versões.
PUT	/v1/projects/{id}/devices/{deviceId}/firmware	Atualizar, forçar e migrar firmware ficam só na tela do Studio SHC: uma falha pode deixar o equipamento inoperante e exigir gravação no local. A API local só consulta as versões.
PATCH	/v1/projects/{id}/devices/{deviceId}/firmware	Atualizar, forçar e migrar firmware ficam só na tela do Studio SHC: uma falha pode deixar o equipamento inoperante e exigir gravação no local. A API local só consulta as versões.
DELETE	/v1/projects/{id}/devices/{deviceId}/firmware	Atualizar, forçar e migrar firmware ficam só na tela do Studio SHC: uma falha pode deixar o equipamento inoperante e exigir gravação no local. A API local só consulta as versões.

Formato do preset

O corpo de Cria um preset, Edita um preset e Valida um preset segue estes formatos.

Preset

Calculados pelo Studio (se vierem no corpo, são ignorados): nomeKey, fabricanteKey, buscaTokens, chaveDuplicata, versao, id, presetId, uid, autorUid, autorNome, autorVerificado, disabled, ratingMedia, ratingCount, ratingSoma, createdAt, updatedAt.

Campo	Tipo	Obrigatório	Para que serve
nome	texto	sim	Nome do equipamento controlado.
fabricante	texto	sim	Fabricante.
categoria	tv, receiver, multiroom, projetor, matrizVideo, arCondicionado, cortina, bridgeIrRf, releWifi, cameraNvr, mediaPlayer, generico	não	Categoria do equipamento.
linhaSerie	texto	não	Linha ou série.
modelosCompativeis	texto	não	Modelos compatíveis.
faixaFirmwareAno	texto	não	Faixa de firmware ou ano.
descricao	texto	sim	O que o preset controla e como preparar o equipamento.
variaveis	lista de PresetVariavel	não	Campos que o instalador preenche ao aplicar o preset, usados como {{nome}} nos comandos.
comandos	lista de PresetComando (mín. 1 item)	sim	Comandos do preset.
statusConfianca	rascunho, testadoEmCampo	não	Auto-declarado pelo autor.
notasDaVersao	texto	não	Obrigatória ao editar (PATCH), até 300 caracteres: o que mudou nesta versão. Não herda a nota da versão anterior.
presetOrigemId	texto	não	Preset do qual este foi derivado.
comunicacao	PresetComunicacao	não	Como o app conversa com o aparelho: formato, tempos, autorizações, regras de resposta, corpo em erro HTTP e chaves sensíveis. As leituras ficam em comandos[i].leituras.
motorMinimo	inteiro	não	Versão mínima do motor de disparo (reservado).
transporte	texto	não	Formato antigo (transporte no topo); descartado com aviso. Hoje o transporte é de cada ação.
tcp	objeto	não	Formato antigo (destino TCP no topo); descartado com aviso. Hoje o destino é de cada ação.

PresetVariavel

Campo	Tipo	Obrigatório	Para que serve
nome	texto	sim	Usado como {{nome}}; letras, números e underline.
tipo	ip, porta, mac, inteiro, decimal, texto, senha, opcoes, hex, booleano, regex, pareamento	não	Tipo do campo (decide a validação na instalação).
label	texto	não	Texto pedido a quem instala (vazio usa o nome).
ajuda	texto	não	De onde tirar o dado.
obrigatorio	true ou false	não
valorDefault	texto	não	Valor sugerido.
min	número	não
max	número	não
opcoes	lista de PresetOpcaoDeVariavel	não
regex	texto	não	Expressão (tipo regex).
mensagemRegex	texto	não	Mensagem quando não casa.
larguraBytes	inteiro (mín. 1)	não
tokenLigado	texto	não	Valor ligado (tipo booleano).
tokenDesligado	texto	não	Valor desligado (tipo booleano).

PresetOpcaoDeVariavel

Campo	Tipo	Obrigatório	Para que serve
label	texto	sim	Texto mostrado.
valor	texto	sim	Valor usado.

PresetComando

Campo	Tipo	Obrigatório	Para que serve
id	texto	não	Id estável; gerado quando falta.
index	inteiro	não	Número do comando, nunca reusado; mantido nos existentes. Num comando novo sem index, o maior já usado + 1; um index informado num comando novo é aceito se for inteiro >= 1 e nunca usado neste preset.
ordem	inteiro	não	Posição; renumerada pela ordem da lista.
nome	texto	sim	Nome único no preset.
descricao	texto	sim	O que o comando faz.
acoes	lista de PresetAcao (mín. 1 item, máx. 5 itens)	sim
variaveis	lista de PresetVariavel	não	Campos só deste comando.
leituras	lista de PresetLeitura	não	Valores lidos da resposta.

PresetAcao

Campo	Tipo	Obrigatório	Para que serve
id	texto	não	Id estável da ação.
ordem	inteiro	não
transporte	tcp, udp, wol, http, delay, websocket	não	Como a ação é enviada (padrão tcp).
ipTemplate	texto	não	IP fixo ou {{campo}}.
portaTemplate	texto	não	Porta fixa ou {{campo}}.
modoEdicao	texto, hex	não	Como o payload é escrito (tcp/udp).
payloadTemplate	texto	não	Comando (tcp/udp); aceita {{campo}}.
terminador	nenhum, cr, lf, crlf, custom	não	Fim do comando (tcp/udp).
terminadorCustom	texto	não	Terminador personalizado.
broadcastWol	texto	não	Destino IPv4 do WoL, padrão 255.255.255.255.
portaWol	inteiro (mín. 1, máx. 65535)	não
janelaRespostaMs	inteiro (mín. 0, máx. 60000)	não
eventosDeErroWs	lista de texto (mín. 1 caracteres, máx. 300 caracteres) (máx. 20 itens)	não
respostaAposEnviarWs	true ou false	não
macTemplate	texto	não	MAC fixo ou {{campo}} (wol).
delayMs	inteiro (mín. 1, máx. 30000)	não	Espera (delay), em ms.
metodoHttp	texto	não	Método HTTP (http).
caminhoHttp	texto	não	Caminho (http/websocket).
corpoHttp	texto	não	Corpo (http).
autorizacaoId	texto	não	Canal de autorização da ação; omitido usa seleção automática.
formatoConteudo	auto, texto, json, formulario	não	Formato do corpo HTTP.
esquemaHttp	http, https	não	http/https (ws/wss no websocket).
headersHttp	lista de PresetCabecalho	não
timeoutMs	inteiro (mín. 1, máx. 60000)	não	Espera da resposta, em ms.
tempoDeConexaoMs	inteiro (mín. 1, máx. 30000)	não	Prazo para abrir a conexão (tcp/http/websocket).
capturaCampo	texto	não	Campo (tipo pareamento) que guarda a resposta.
capturaCaminho	texto	não	Onde o valor está na resposta.
mensagemWs	texto	não	Mensagem enviada (websocket).
esperarEventoWs	texto	não	Evento esperado (websocket).

PresetCabecalho

Campo	Tipo	Obrigatório	Para que serve
nome	texto	sim	Nome do cabeçalho HTTP.
valor	texto	não	Valor; aceita {{campo}}.

PresetLeitura

Campo	Tipo	Obrigatório	Para que serve
rotulo	texto	sim	O que o valor é (ex.: “Volume”).
caminho	texto	sim	Onde o valor está na resposta (ex.: result.volume).

PresetComunicacao

Campo	Tipo	Obrigatório	Para que serve
formato	texto	não	Formato do conteúdo dos pedidos (ex.: json, texto); vazio = automático. Ainda não muda o envio.
tempoPadraoMs	inteiro (mín. 1, máx. 60000)	não	Espera padrão da resposta, em ms.
tempoDeConexaoMs	inteiro (mín. 1, máx. 30000)	não	Prazo padrão para abrir a conexão, em ms.
autorizacoes	lista de PresetAutorizacao	não
regrasDeResposta	lista de PresetRegraDeResposta	não
corpoEmErroHttp	true ou false	não	Ler o corpo também em resposta HTTP de erro.
chavesSensiveis	lista de texto	não	Pedaços de nome de chave cujo valor é mascarado no log e na resposta mostrada, além dos que o app já mascara sempre.

PresetAutorizacao

Campo	Tipo	Obrigatório	Para que serve
id	texto	sim	Id da autorização.
nome	texto	não	Nome.
tipo	bearer, apiKey, oauth2, basic, nenhuma, jwtBearer, awsSignature, pareamentoNoAparelho	não	Tipo da autorização.
campos	lista de texto	não	Campos (variáveis) que guardam o segredo.
comandoDePareamentoId	texto	não	Comando que pareia.
captura	objeto	não
envio	objeto	não
aoRecusar	pedirPareamento, soAvisar, refazerLogin	não	O que fazer quando o aparelho recusa.
tentativas	inteiro (mín. 0, máx. 5)	não
renovacao	objeto	não
avisoDeDemoraMs	inteiro (mín. 0, máx. 60000)	não
textos	objeto	não
obrigatorio	true ou false	não

PresetRegraDeResposta

Campo	Tipo	Obrigatório	Para que serve
aplicaA	todas, http, websocket	não	Transporte a que a regra se aplica.
autorizacaoId	texto	não	Autorização a que a regra se refere.
quando	PresetCondicaoDeResposta	sim
soComToken	true ou false	não
significa	tokenRecusado, pedidoNegado, semRespostaNaTela, falha, sucesso	não	O que a resposta significa.
mensagem	texto	não	Mensagem mostrada.

PresetCondicaoDeResposta

Campo	Tipo	Obrigatório	Para que serve
tipo	statusHttp, jsonCaminho, textoContem, regex, eventoWs, jsonRpc, cabecalho	não	Tipo da condição.
status	lista de inteiro (mín. 100, máx. 599)	não
caminho	texto	não	Caminho no JSON.
valores	lista de texto ou número ou true ou false	não
texto	texto	não	Texto ou regex.
nome	texto	não	Nome do evento ou do cabeçalho.