A API da WisyLink cria e atualiza sites hospedados direto do seu código. Envie arquivos de referência e uma mensagem em linguagem natural para POST /chat: o agente constrói e hospeda o site em um endereço próprio no wisylink.com. Para alterá-lo, envie outra mensagem com o mesmo id. A API consome a cota de 5 horas e semanal do plano.
- Poucos endpoints REST cobrem todo o ciclo de vida: enviar arquivos, criar ou continuar um site com
POST /chat, consultar o status, listar e excluir sites. POST /chatconversa com a Wisy, a mesma assistente do app, então a resposta pode ser uma pergunta em vez de uma construção. Confira ostatusantes de começar a consultar.- As chaves de API são criadas na web, e cada uma tem um teto de gasto próprio, de até US$ 10 por dia, semana ou mês, além das janelas do seu plano.
- O pacote npm
@wisylink/clireúne os mesmos endpoints em uma ferramenta de linha de comando e em um cliente Node. - Domínios próprios e chaves de serviços (Stripe, e-mail) são configurados no app web ou nos apps para celular; a API pública não cobre essa parte.
O que dá para automatizar
A API é o chat sem a janela do chat. Cada POST /chat é uma mensagem para a Wisy; quando o pedido está claro, um agente de construção de IA escreve um app web renderizado no servidor e o publica em https://<id>.wisylink.com, com dados salvos, contas ou envio de arquivos quando o briefing pede. Não há parâmetros de template, tema ou tipo de página. Tudo sobre o site, de seções e textos a funcionalidades e estilo, vai na mensagem, do jeito que uma pessoa descreveria. (Para os conceitos por trás disso, veja o que é um criador de aplicativos com IA.)
A URL base é https://api.wisylink.com. Autentique com o cabeçalho x-api-key: <chave> ou com Authorization: Bearer <chave>. Os endpoints JSON recebem Content-Type: application/json, e os timestamps vêm em milissegundos desde a época Unix (epoch).
| Endpoint | Método | Para que serve | Campos principais |
|---|---|---|---|
/files | POST | Iniciar o envio de um arquivo | name na entrada, id na saída |
/files/chunks | POST | Enviar os bytes do arquivo, no máximo 4 MB por requisição | id e last=true na última parte; corpo binário bruto |
/files/:id | GET | Ler os metadados do arquivo | content_type, name, size |
/files/:id | DELETE | Excluir um arquivo | Também sai dos file_ids de qualquer link |
/chat | POST | Criar um site (sem id) ou continuar um (com id) | message, até 10 file_ids; devolve id, url, status, answer |
/links | GET | Listar seus sites, do mais novo para o mais antigo | page, limit (de 1 a 100); items, total_pages, has_next |
/links/:id | GET | Ler um site | status, url, file_ids |
/links/:id | DELETE | Excluir um site e seus arquivos de referência | Devolve {"ok": true} |
O que a API pública não faz: definir as chaves de que um site precisa para pagamentos ou e-mail (o dono cola esses dados em Integrações), conectar um domínio próprio, ler ou gravar os dados salvos de um site ou exportar o código-fonte.
Gere uma chave de API com limite de gasto próprio
- Entre em wisylink.com. As chaves são criadas só na web, não nos apps para celular.
- Abra Chaves de API nas configurações da conta e escolha Gerar chave.
- Dê à chave o nome do lugar onde ela vai rodar, como “acme-landing-pages-ci”, para saber o que vai quebrar quando você a revogar.
- Defina a janela e o teto. Escolha Diário, Semanal ou Mensal e um limite de gasto em dólares, de até US$ 10 por janela. As janelas seguem um dia em UTC, uma semana que começa na segunda-feira ou um mês.
- Copie a chave na hora. Ela aparece uma única vez. Guarde-a no seu gerenciador de segredos ou nos segredos da CI, por exemplo como
WISYLINK_API_KEY.
O teto é uma trava de segurança, não o seu plano. Toda requisição também consome as janelas móveis de 5 horas e semanal da sua conta, as mesmas do chat na web e no celular, medidas pelo trabalho de IA que a requisição dispara, inclusive a leitura dos seus arquivos de referência. O teto é conferido antes de cada requisição e o gasto é registrado depois, então a última requisição de uma janela pode passar um pouco do limite. Revogar uma chave a exclui na hora, e tudo o que ainda a usa passa a receber 401.
Dá para usar a API no plano gratuito? Dá. No Community valem as mesmas regras do app: uma construção por janela de 5 horas, e os sites ficam no ar por 30 dias, mais uma semana marcados para exclusão. Isso basta para prototipar uma integração; para trabalhos de clientes ou lotes, um plano pago dá mais cota de uso, construções em paralelo e links que ficam no ar enquanto você for assinante.
Envie arquivos de referência (envio em partes)
Arquivos de referência são tudo o que o agente deve ler ou colocar no site: um manual da marca, um logo, fotos de produtos, uma tabela de preços. Os formatos aceitos são JPEG, PNG, WebP, GIF, HEIC, SVG, MP3, MP4, PDF, XLSX, DOCX, CSV, TXT, JSON e HTML, com até 25 MB cada. O tipo real é detectado pelos bytes, e arquivos vazios são recusados.
O envio leva duas chamadas. Primeiro, crie o arquivo e guarde o id retornado:
curl -s -X POST https://api.wisylink.com/files -H "x-api-key: $WISYLINK_API_KEY" -H "Content-Type: application/json" -d '{"name":"manual-da-marca.pdf"}'
Depois, envie os bytes. Um arquivo de até 4 MB vai em uma única requisição com last=true:
curl -s -X POST "https://api.wisylink.com/files/chunks?id=$FILE_ID&last=true" -H "x-api-key: $WISYLINK_API_KEY" -H "Content-Type: application/octet-stream" --data-binary @manual-da-marca.pdf
Para arquivos maiores, divida-os (split -b 4m manual-da-marca.pdf parte_), envie as partes em ordem para o mesmo id e acrescente last=true só na última; essa chamada finaliza e processa o arquivo. O envio precisa terminar em até 15 minutos, ou a sessão expira. Em Node, o cliente descrito mais abaixo faz a divisão em partes por você.
Crie um site com POST /chat e espere a URL no ar
Envie o briefing
Omita o id para começar um site novo. A mensagem pode ter até 5.000 caracteres, espaço suficiente para um briefing de verdade: objetivo, público, seções, textos reais, funcionalidades, estilo e idioma. Termine com “escolha padrões sensatos para tudo o que eu não especifiquei” para aumentar a chance de a construção começar já na primeira chamada. Troque FILE_ID pelo id do seu envio.
curl -s -X POST https://api.wisylink.com/chat -H "x-api-key: $WISYLINK_API_KEY" -H "Content-Type: application/json" -d '{"message":"Crie uma landing page de uma página para a Brasa, uma torrefação de cafés especiais em Belo Horizonte. Seções: destaque principal, três cafés de origem única com preços, formulário de pedidos de atacado salvo em uma área administrativa, horário de funcionamento, link para o mapa. Use o manual da marca anexo para cores e fontes. Escolha padrões sensatos para tudo o que eu não especifiquei.","file_ids":["FILE_ID"]}'
A mesma chamada em Node, com fetch:
const res = await fetch("https://api.wisylink.com/chat", { method: "POST", headers: { "x-api-key": process.env.WISYLINK_API_KEY, "Content-Type": "application/json" }, body: JSON.stringify({ message: brief, file_ids: [fileId] }) }); let link = await res.json();
Um site novo devolve 201 com id, url, status, answer, created_at e updated_at. Guarde o id: é com ele que você altera, lê ou exclui o site depois. Trate-o como uma string opaca, sem validar o formato.
Leia o status antes de consultar
O status na resposta do POST /chat diz se uma construção começou de fato:
buildingouqueued- Uma construção está rodando ou esperando uma vaga livre (
queuedainda não está na lista da referência, mas aparece na prática). Comece a consultar. Em um site novo, aurlmostra uma página de “em construção” até a primeira construção terminar. idleem um site novo- Nenhuma construção começou. A Wisy respondeu, e o
answernormalmente traz uma pergunta curta, como qual provedor de pagamento usar. Responda com outroPOST /chatcom o mesmoid. completedouabortedlogo depois de uma continuação- Em um site existente, o status mostra o resultado da última construção. Se ele não mudou para
building, sua mensagem recebeu uma resposta, não uma construção; leia oanswer.
Consulte até a construção terminar
Não há webhooks, então consulte GET /links/:id periodicamente (polling). Construções levam minutos, não segundos, e uma consulta a cada 15 a 30 segundos é mais que suficiente. Trate qualquer status diferente de completed, aborted ou idle como ainda em andamento, o que mantém o seu loop seguro se surgir um novo status intermediário:
const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); while (!["completed", "aborted", "idle"].includes(link.status)) { await sleep(20000); link = await (await fetch(`https://api.wisylink.com/links/${link.id}`, { headers: { "x-api-key": process.env.WISYLINK_API_KEY } })).json(); }
Quando o status for completed, a url é o seu site no ar. aborted significa que a construção parou antes de terminar; um site que já estava no ar mantém a versão anterior, e uma nova mensagem tenta de novo. Se o site ganhar um domínio próprio mais tarde, a url passa a devolver esse domínio. O relatório completo da construção, incluindo qualquer aviso de que o site espera chaves da Stripe ou de e-mail, fica no chat daquele link no app web.
Continue, liste e exclua links
Para alterar um site, envie só a nova instrução, com o id dele no lugar de LINK_ID; o servidor guarda o histórico da conversa, e um site continuado responde 200:
curl -s -X POST https://api.wisylink.com/chat -H "x-api-key: $WISYLINK_API_KEY" -H "Content-Type: application/json" -d '{"id":"LINK_ID","message":"Adicione uma segunda unidade: Rua Pernambuco, 412, aberta todos os dias das 7h às 15h."}'
Consulte de novo do mesmo jeito. Cada mudança é uma nova construção; uma que falha deixa a última versão boa no ar, enquanto uma bem-sucedida entra no ar assim que termina, então rode seus testes depois de cada mudança. Espere uma construção terminar antes de mandar a próxima mudança, a não ser que a nova mensagem corrija a construção em andamento.
Para listar os sites, percorra GET /links?page=1&limit=100 até has_next ser false. Para remover um, DELETE /links/:id exclui o site e os arquivos de referência ligados a ele. Um domínio próprio que ele usava continua na sua conta, pronto para outro site.
A CLI e o cliente Node
O pacote @wisylink/cli (licença MIT, Node 18.17 ou superior) mapeia os comandos um a um para os endpoints acima, o que faz dele o jeito mais rápido de automatizar a WisyLink a partir de um terminal ou de um job de CI:
npm i -g @wisylink/clie depoisexport WISYLINK_API_KEY=..., ou passe--api-keyem cada comando.wisylink files upload ./manual-da-marca.pdfenvia em partes de 4 MB automaticamente.wisylink chat --message "Crie uma landing page para a Brasa Cafés." --file-id FILE_IDcria um site.wisylink links list --page 1 --limit 50lista seus sites.
Os comandos imprimem JSON, então o jq consegue extrair o id ou a url. --timeout aceita de 1.000 a 120.000 milissegundos; aumente o valor no chat, que espera a resposta da Wisy.
O mesmo pacote exporta um cliente Node: import { CreateWisyLinkClient } from "@wisylink/cli"; const client = CreateWisyLinkClient({ apiKey: process.env.WISYLINK_API_KEY }); const file = await client.uploadFile("./manual-da-marca.pdf"); const link = await client.chat({ message: brief, fileIds: [file.id] });
Duas observações de versão, válidas para a versão 0.2.1 publicada no npm. Primeiro, os comandos e métodos do cliente que recebem um id de link (chat --link-id, links get, links delete e, no Node, linkId, getLink, deleteLink) validam os ids contra um formato antigo e recusam os atuais, então continue, leia e exclua sites por HTTP, como mostrado acima. Segundo, a documentação da CLI (em inglês) já descreve uma versão mais nova, com login pelo navegador (wisylink login), chat interativo com o progresso da construção ao vivo e a opção --json; rode wisylink --version para ver qual você tem.
Limites, erros e boas práticas
Os erros voltam em JSON, com um código em error. Os que merecem tratamento explícito:
429 limit_reached- A janela de 5 horas ou a semanal do seu plano se esgotou (
reasoné5h_limitouweekly_limit). Agende a nova tentativa parareset_at, em milissegundos epoch, em vez de repetir em loop. 429 credit_limit_exceeded- Esta chave atingiu o próprio teto de gasto. Pode acontecer em qualquer endpoint; espere até
resets_atou aumente o teto (até US$ 10) na web. 429 build_concurrency_limit- Há construções demais rodando para o seu plano. Espere uma terminar e então envie a próxima.
429 rate_limited- Requisições demais em pouco tempo. Recue e tente de novo.
400 bad_request- JSON inválido, mensagem vazia ou com mais de 5.000 caracteres, ou ids de arquivo que não existem (listados em
missing_file_ids). Atenção: só os 10 primeirosfile_idssão usados; os excedentes são descartados sem erro. 401,404,500 chat_unavailable- Chave ausente ou revogada; link ou arquivo que não é seu; Wisy indisponível por um momento, o que vale uma nova tentativa depois de uma pausa.
Hábitos que economizam dinheiro e dor de cabeça:
- Mantenha as chaves no servidor. Nunca coloque uma chave em código de navegador ou de app. Use uma chave por cliente ou por pipeline, para que cada uma tenha o próprio teto e possa ser revogada sozinha.
- Não repita o
POST /chatàs cegas. A chamada não é idempotente: uma requisição que estourou o tempo do seu lado pode ter criado um site ou iniciado uma construção mesmo assim. ConfiraGET /links(do mais novo para o mais antigo) antes de reenviar e dê à chamada um timeout de cliente de um minuto ou mais. - Enfileire os lotes. Rode tantas construções simultâneas quanto o seu plano permite e trate
build_concurrency_limitcomo sinal para esperar. - Revise antes de entregar. O resultado da IA pode conter erros. Abra cada site, teste os formulários e leia os textos antes que um cliente ou o público veja; os termos da WisyLink deixam a revisão e os testes sob sua responsabilidade.
Casos de uso: agências, eventos e ferramentas internas
Landing pages de agência. Mantenha um modelo de briefing com espaços para o nome do cliente, a oferta, as seções e o tom, preencha-o a partir do seu CRM e anexe o logo e o manual da marca do cliente como arquivos. Cada campanha vira um site próprio, o retorno do cliente vira mensagens de continuação, e uma chave por cliente mantém os gastos separados. Conecte o domínio do cliente em Domínios, em qualquer plano, assim que a página for aprovada; um plano pago mantém o site no ar depois dos 30 dias gratuitos. Um exemplo completo da página em si está em como criar uma landing page de lista de espera com IA.
Minissites por evento. Uma linha por evento em uma planilha (nome, data, local, capacidade) vira um site de confirmação de presença por evento, criado por um script que guarda cada id retornado ao lado da linha correspondente. O guia para criar uma página de confirmação de presença com IA mostra o que colocar em cada briefing. Depois do evento, exclua o site ou mantenha-o como arquivo em um plano pago.
Automações internas. Um script pode criar a primeira versão de uma ferramenta interna, como um controle de estoque ou um quadro de aprovações. Mas não refaça a construção para atualizar dados: peça à Wisy um endpoint para o qual seus sistemas possam enviar registros, protegido por um segredo que você define em Integrações. Registros gravados assim chegam aos visitantes em cerca de um minuto, sem gastar uma construção. Mais sobre esse padrão em ferramentas internas com IA.
Gere sua chave e crie seu primeiro site pelo código
Crie uma conta grátis, gere uma chave de API com um teto baixo e envie seu primeiro briefing com a chamada curl acima. Deixe a referência da API (em inglês) aberta para os detalhes de cada campo e, quando a integração passar de protótipo a produção, escolha na seção de preços um plano com a cota de construções e as construções em paralelo que o seu volume exige.
F.A.Q.