Changelog da API
O que mudou na API e no painel, do mais novo para o mais antigo. Mudança que quebra algo avisa antes e aparece aqui com a data. A data é o dia em que a mudança entrou no código do Praeko.
Posts de imagem (foto única) no Instagram
POST /v1/posts aceita kind: "image" com uma foto em media.images ([{ media, alt }]), e POST /v1/media aceita type: image (só JPEG; o servidor confere o arquivo e lê a largura e a altura). A foto sai pelo Instagram, pelo Buffer ou direto pela Meta (via). O Instagram aceita JPEG de até 8 MB, com proporção de 4:5 a 1,91:1; o texto alternativo (alt, até 1000 caracteres) vai pela Meta e, pelo Buffer, é ignorado e o item volta com o aviso alt_ignored em items[].warnings. YouTube e TikTok recusam kind: image (kind_not_supported_by_network) e mais de uma imagem (carrossel) ainda não existe (carousel_not_supported). A resposta do post ganha kind e media.images. Erros novos: invalid_image, image_too_large, image_aspect_ratio, kind_not_supported_by_network, carousel_not_supported. No Studio, format: image e praeko studio slides geram a foto em 1080x1350. SDK: tipos aditivos (kind, media.images, type: image); media.video pode ser null num post de imagem.
Servidor MCP local do Studio no npm
@praeko/studio-mcp 0.1.1 está no npm: um servidor MCP que roda na sua máquina (por stdio, sem abrir porta) e dá a um agente sem terminal, como o Claude Desktop, 14 ferramentas do Studio (studio_status, studio_new_episode, studio_voice, studio_render, studio_upload e outras). O fluxo é criar, renderizar, studio_upload (devolve só o mediaId, em duas etapas) e publicar com create_post no servidor MCP remoto praeko: o servidor local nunca publica. A voz final também pede confirmação. Precisa de Node, de Chrome/Remotion para renderizar e das suas chaves, tudo na sua máquina. Veja Studio no Claude Desktop: o servidor MCP local.
Praeko Studio 0.2.1 a 0.2.3
O praeko studio init agora é interativo: num terminal ele pergunta o nome, o público, o tom, as cores, a fonte e até 3 referências (Enter pula cada pergunta) e escreve brief.md e um rascunho de playbook.md que o agente lê antes do primeiro roteiro. O novo praeko studio brief reabre a entrevista num projeto existente. Com --yes (ou sem terminal), init importa as cores e a fonte da marca (--brand ou ../brand/build/tokens.json). O doctor ganhou uma seção de voz, com as contas e as vozes configuradas. voice account add guarda a chave mesmo sem achar a voz. Comandos e arquivos seguem em inglês; para um projeto do 0.1.x, rode praeko studio migrate --dry-run e depois praeko studio migrate. @praeko/studio, studio-core e studio-kit estão no npm na 0.2.3. Veja Praeko Studio.
CLI 0.4.0: só inglês
A CLI praeko deixa de aceitar os comandos e as opções antigos em português e passa a escrever as mensagens em inglês. As variáveis PRAEKO_SEGREDOS e PRAEKO_SEM_CHAVEIRO viraram PRAEKO_SECRETS e PRAEKO_NO_KEYCHAIN, e o arquivo de chaves de ~/.config/praeko/segredos.json para secrets.json (renomeie o seu). Os caminhos antigos da API em português seguem como estavam. Está no npm como @praeko/cli 0.4.0. Veja SDK e CLI.
Praeko Studio 0.2.0: tudo em inglês
Mudança incompatível feita de uma vez, no começo: comandos, flags, arquivos e chaves do Studio agora são em inglês (novo virou new, voz virou voice, compilar virou compile, folha virou contact-sheet, agendar virou schedule, --qualidade virou --quality, marca.json virou brand.json, episodio.yaml virou episode.yaml, e assim por diante). Não há aliases em português. Para um projeto criado pelo 0.1.x, rode praeko studio migrate --dry-run e depois praeko studio migrate: ele renomeia arquivos e chaves, ajusta os imports e guarda um backup em .studio-backup/. As mensagens saem em inglês; --lang pt traz as mais comuns em português. Com --engine hyperframes, o vídeo e a capa saem sem nada do Remotion. Veja Praeko Studio.
Praeko Studio no npm
@praeko/studio (comando praeko-studio), @praeko/studio-core e @praeko/studio-kit estão no npm, com licença MIT para o nosso código. O Studio faz vídeos curtos e longos que você opera com o seu próprio agente de código (Claude Code, Codex, Gemini CLI, Cursor, opencode), na sua máquina, e publica pelo Praeko só depois do seu sim. O Remotion, motor padrão, não é MIT: grátis até 3 pessoas. Veja Praeko Studio.
praeko studio entrega ao Studio instalado
A CLI 0.3.0 passa o comando praeko studio ao @praeko/studio (no projeto, ao lado da CLI, na instalação global ou no PATH) e, sem ele, mostra como instalar. Antes só avisava que o Studio não era distribuído.
Endereços do painel e da entrada em inglês
Os endereços do painel agora são em inglês: #/publish, #/create, #/channels, #/media, #/keys, #/usage, #/settings, #/waitlist e a entrada em /sign-in. Os endereços antigos continuam funcionando: o painel reescreve #/publicar, #/config/notificacoes, #/definir-senha?token=… e os demais para os novos, /entrar redireciona (301) para /sign-in e os links de convite, redefinição de senha e conexão de agentes já enviados seguem válidos. Na API, os caminhos em português (/v1/canais, /saude, /conexoes/:rede/retorno) continuam respondendo, agora com a seção Caminhos descontinuados explicando como migrar; as âncoras das páginas de docs também ficaram em inglês (#scopes, #parameters), com as antigas ainda resolvendo.
Endereços das docs sempre em inglês
Os endereços da documentação em português passaram a ser os mesmos do inglês, só com o prefixo de idioma: /docs/get-started, /docs/guides/webhooks, /docs/agents/claude-code, /docs/api/posts/create-post (e /docs/en/... no inglês). Os endereços antigos em português (/docs/comecar, /docs/guias/..., /docs/api/posts/criar-post) redirecionam com 301 para os novos.
Documentação em inglês e passo "Seu primeiro vídeo"
Toda a documentação pública ganhou uma versão em inglês em /docs/en, com seletor de idioma e busca própria de cada idioma. O Começar tem um passo novo, "Seu primeiro vídeo", com o caminho pelo SDK, pela CLI e pelo agente.
YouTube: mudar um vídeo já enviado e ainda agendado
PATCH /v1/posts/:id muda o horário (pelo menos 5 minutos à frente), o título, a descrição, as etiquetas, a categoria e o comentário fixo de um vídeo que o Praeko já subiu como privado com horário de publicação. O servidor confere o vídeo ao vivo antes de escrever e a resposta traz itemResults por item; vídeo que já está público responde 409 video_not_private. Em DELETE /v1/posts/:id, dismiss=true tira o horário (o vídeo fica privado) e dismiss=true&delete_video=true apaga o vídeo; sem isso, o YouTube publica no horário. No MCP, a prévia de update_post diz o que vai mudar (will_change) e o que não pode (cannot_change). Veja Publicar um vídeo.
Nova tela de entrada
A entrada no painel foi redesenhada: chave de acesso como caminho principal, e-mail e senha, segundo fator e um modo de recuperação que entra com a chave de API (ela fica só naquela aba).
Convites e Esqueci minha senha
Quem é convidado da lista de espera recebe um e-mail, em português ou inglês, com um link de 7 dias para criar a senha. Na tela de entrada, Esqueci minha senha manda um link de uso único, válido por 1 hora; a resposta é sempre a mesma, exista a conta ou não. Ao salvar a senha nova, as outras sessões da pessoa são encerradas.
Mídia servida por praeko.app
As URLs públicas das mídias (publicUrl) passam a usar o domínio praeko.app.
Foto de perfil do Instagram
O canal do Instagram conectado pela API da Meta ganha a foto de perfil da conta (em GET /v1/channels/instagram/avatar e no painel). Ela é copiada ao conectar, em Verificar agora e a cada 3 dias.
Avisos no painel e por e-mail
O sino do painel mostra os avisos de post enviado, falha, nova tentativa, resumo semanal e comentário novo do YouTube, com marcar como lido. Pela API: GET /v1/notifications e POST /v1/notifications/read (os avisos são por pessoa, então com chave de API a lista vem vazia). Por e-mail: o resumo semanal às segundas e os comentários novos do YouTube, no máximo um e-mail por hora. Cada pessoa escolhe em Configurações › Notificações; por padrão, nenhum e-mail e os avisos do painel ligados. Os avisos ficam 30 dias.
MCP: entrar com OAuth
Conectores que usam OAuth (como o do Claude.ai) entram em https://praeko.app/mcp pelo login do Praeko, sem colar chave: o agente abre a tela de consentimento e você gerencia as conexões em Chaves de API › Conexões de agentes. A chave de API no cabeçalho Authorization: Bearer continua valendo. Veja Servidor MCP.
MCP: enviar um arquivo local
As ferramentas create_media_upload, complete_media_upload e get_media (agora são 18) deixam um agente com shell publicar um vídeo que está no disco: o servidor prepara o envio, o agente roda o curl com a chave do ambiente e confirma. Sem código de confirmação (não publica nada), com limites de tamanho, de envios pendentes e de validade. Veja Servidor MCP.
Painel em inglês
As telas do painel ganharam a versão em inglês, inclusive as mensagens dos códigos de erro da API. Escolha o idioma em Configurações.
SDK e CLI no npm
@praeko/sdk 0.1.2 e @praeko/cli 0.1.1 estão no npm, com licença MIT e o código em github.com/Praeko/praeko-js. O CLI tem um só comando, praeko, então npx @praeko/cli --help funciona. Veja SDK e CLI.
Endereço da API em praeko.app
A documentação e os exemplos usam https://praeko.app como endereço base. GET /health responde service: "praeko".
Documentação pública em praeko.app/docs
Referência de todas as rotas, cada uma com resposta de exemplo, status de sucesso e exemplo em 10 linguagens; guias, páginas para cada agente de IA, busca, llms.txt e uma cópia em Markdown de cada página (acrescente .md à URL).
Servidor MCP remoto
Um endereço, https://praeko.app/mcp, para agentes de IA lerem as docs, consultarem canais, mídia, posts, calendário, métricas e uso, e criarem, agendarem, editarem e cancelarem posts, subirem mídia por URL e criarem ideias. Criar, agendar, editar e cancelar posts, subir mídia por URL e criar ideias pedem dois passos (prévia e código de confirmação). Veja Servidor MCP.
Cabeçalho Idempotency-Key
Mande Idempotency-Key em POST, PATCH e DELETE e a repetição devolve a resposta da primeira vez, com Idempotent-Replayed: true, sem criar nada de novo. A chave vale 24 horas. Chave reusada com outro pedido: 422 idempotency_key_reuse; pedido ainda em andamento: 409 idempotency_in_progress. O SDK ganhou a opção idempotencyKey e o CLI a opção --idempotency-key. Veja Repetir uma requisição.
Retenção, impressões e CTR
GET /v1/insights/retention e GET /v1/insights/:item/retention trazem a curva de retenção, as impressões e o CTR do YouTube, e o alcance e o tempo de exibição do Instagram. Número que a rede não entrega vem null, nunca 0. O Instagram ganhou também pulos de reels, republicações, novos seguidores e visitas ao perfil. A conexão do YouTube passa a pedir a permissão de Analytics: canal conectado antes aparece como reauthorize até você reconectar. Veja Métricas, retenção e CTR.
Chaves de acesso (passkeys)
Entre no painel com uma chave de acesso (WebAuthn), com a biometria ou o PIN do aparelho. A verificação do usuário é obrigatória, e você gerencia as chaves de acesso em Configurações.
Preferências, tema e idioma
GET /v1/preferences e PUT /v1/preferences guardam o tema, o idioma e as preferências de aviso por e-mail e no painel (por padrão, nenhum e-mail de aviso). O painel ganhou tema claro, escuro ou do sistema e o idioma português ou inglês.
Ideias no servidor
O quadro Criar deixa de morar no navegador: GET, POST, PATCH e DELETE em /v1/ideas, mais POST /v1/ideas/import (até 500 por chamada, repetível). Colunas idea, scripting, ready e posted. Erros novos: idea_not_found e idea_limit_reached. O SDK ganhou praeko.ideas.
Duração e dimensões do vídeo
A mídia de vídeo traz durationMs, width e height, lidos do cabeçalho do MP4 ou MOV. Vídeos antigos ganham os valores na primeira leitura.
Webhooks de saída
Cadastre uma URL em /v1/webhooks (escopo admin) e receba post.sent, post.failed e post.scheduled-fail. Cada entrega vem assinada com HMAC, com novas tentativas espaçadas e desativação automática do webhook que só falha. Endereços internos são recusados. O SDK ganhou praeko.webhooks e o CLI praeko webhook. Veja Webhooks.
Uso e log
GET /v1/usage resume as chamadas (total, erros, p95, pico por minuto, por dia e por chave) e GET /v1/usage/log lista as requisições dos últimos 30 dias, só com metadados. O CLI ganhou praeko usage e praeko usage log.
Posts criados fora do Praeko
O que você publica direto na rede passa a aparecer sozinho em Enviados, a cada 15 minutos por canal (YouTube, TikTok e Instagram), marcado como "Fora do Praeko". GET /v1/content os traz com a origem external. Não há webhook para esses posts.
Métricas por item com marcos
Cada item de GET /v1/insights traz postId, tags e milestones (visualizações em marcos de 1 hora a 7 dias, quando gravadas). Alimenta a curva da aba Analytics.
Várias contas por rede
O mesmo workspace pode conectar mais de uma conta do YouTube ou do TikTok. Escolha a conta de cada item pelo channel do post.
Praeko no lugar de Arauto
Chaves praeko_… no lugar de arauto_…, comando praeko e variável PRAEKO_KEY; o cabeçalho passa a ser X-Praeko-Contract. Ainda são aceitos: chaves arauto_…, a variável ARAUTO_CHAVE e o cabeçalho X-Arauto-Contract. O comando antigo arauto não existe mais no @praeko/cli.
Caminhos em português
Os caminhos antigos seguem respondendo, com Deprecation: true e Link com rel="successor-version". A data para desligá-los ainda não foi fixada.
Contrato v1 em inglês
Envie o cabeçalho de contrato en (hoje X-Praeko-Contract: en) e use /v1/posts, /v1/insights e /v1/youtube/videos, com rotas, campos, valores e códigos de erro em inglês. Campos em português são recusados nesse contrato. O SDK e o CLI já falam o contrato novo. Veja Autenticação, erros e limites.