API changelog
What changed in the API and the panel, newest first. A breaking change is announced ahead of time and listed here with its date. The date is the day the change entered the Praeko code.
Image posts (single photo) on Instagram
POST /v1/posts accepts kind: "image" with one photo in media.images ([{ media, alt }]), and POST /v1/media accepts type: image (JPEG only; the server checks the file and reads the width and height). The photo goes out on Instagram, through Buffer or directly through Meta (via). Instagram accepts JPEG up to 8 MB, with an aspect ratio from 4:5 to 1.91:1; the alt text (alt, up to 1000 characters) goes through Meta and, through Buffer, is ignored and the item comes back with the alt_ignored warning in items[].warnings. YouTube and TikTok refuse kind: image (kind_not_supported_by_network) and more than one image (carousel) does not exist yet (carousel_not_supported). The post response gains kind and media.images. New errors: invalid_image, image_too_large, image_aspect_ratio, kind_not_supported_by_network, carousel_not_supported. In Studio, format: image and praeko studio slides render the photo at 1080x1350. SDK: additive types (kind, media.images, type: image); media.video can be null on an image post.
Studio local MCP server on npm
@praeko/studio-mcp 0.1.1 is on npm: an MCP server that runs on your machine (over stdio, no port opened) and gives an agent without a terminal, such as Claude Desktop, 14 Studio tools (studio_status, studio_new_episode, studio_voice, studio_render, studio_upload and others). The flow is create, render, studio_upload (returns only the mediaId, in two steps) and publish with create_post on the remote praeko MCP server: the local server never publishes. The final voice also asks for confirmation. It needs Node, Chrome/Remotion to render and your own keys, all on your machine. See Studio in Claude Desktop: the local MCP server.
Praeko Studio 0.2.1 to 0.2.3
praeko studio init is now interactive: in a terminal it asks for the name, audience, tone, colors, font and up to 3 references (Enter skips each question) and writes brief.md and a draft playbook.md that the agent reads before the first script. The new praeko studio brief reopens the interview in an existing project. With --yes (or without a terminal), init imports the brand colors and font (--brand or ../brand/build/tokens.json). doctor gained a voice section, listing the configured accounts and voices. voice account add keeps the key even when it cannot find the voice. Commands and files stay in English; for a 0.1.x project, run praeko studio migrate --dry-run and then praeko studio migrate. @praeko/studio, studio-core and studio-kit are on npm at 0.2.3. See Praeko Studio.
CLI 0.4.0: English only
The praeko CLI no longer accepts the old Portuguese commands and options and now writes its messages in English. The variables PRAEKO_SEGREDOS and PRAEKO_SEM_CHAVEIRO became PRAEKO_SECRETS and PRAEKO_NO_KEYCHAIN, and the key file moved from ~/.config/praeko/segredos.json to secrets.json (rename yours). The old Portuguese API paths stay as they were. It is on npm as @praeko/cli 0.4.0. See SDK and CLI.
Praeko Studio 0.2.0: everything in English
A breaking change made all at once, early: Studio's commands, flags, files and keys are now English (novo became new, voz became voice, compilar became compile, folha became contact-sheet, agendar became schedule, --qualidade became --quality, marca.json became brand.json, episodio.yaml became episode.yaml, and so on). There are no Portuguese aliases. For a project created by 0.1.x, run praeko studio migrate --dry-run and then praeko studio migrate: it renames files and keys, fixes the imports and keeps a backup in .studio-backup/. Messages are in English; --lang pt brings the most common ones in Portuguese. With --engine hyperframes, the video and the cover come out with nothing from Remotion. See Praeko Studio.
Praeko Studio on npm
@praeko/studio (the praeko-studio command), @praeko/studio-core and @praeko/studio-kit are on npm, with an MIT license for our code. Studio makes short and long videos that you drive with your own coding agent (Claude Code, Codex, Gemini CLI, Cursor, opencode), on your machine, and publishes through Praeko only after your yes. Remotion, the default engine, is not MIT: free up to 3 people. See Praeko Studio.
praeko studio hands over to the installed Studio
CLI 0.3.0 passes the praeko studio command to @praeko/studio (in the project, next to the CLI, in the global install or on the PATH) and, without it, shows how to install. Before, it only said Studio was not distributed.
Panel and sign-in addresses are in English
The panel addresses are now in English: #/publish, #/create, #/channels, #/media, #/keys, #/usage, #/settings, #/waitlist, and the sign-in page is /sign-in. The old addresses keep working: the panel rewrites #/publicar, #/config/notificacoes, #/definir-senha?token=… and the others to the new ones, /entrar redirects (301) to /sign-in, and invitation, password-reset and agent-connection links already sent stay valid. In the API, the Portuguese paths (/v1/canais, /saude, /conexoes/:network/retorno) keep answering, and the new Deprecated paths section explains how to migrate; anchors on the docs pages are English too (#scopes, #parameters), with the old ones still resolving.
Docs URLs are always in English
The Portuguese documentation now uses the same URLs as the English one, with only the language prefix changing: /docs/get-started, /docs/guides/webhooks, /docs/agents/claude-code, /docs/api/posts/create-post (and /docs/en/... for English). The old Portuguese URLs (/docs/comecar, /docs/guias/..., /docs/api/posts/criar-post) redirect with a 301 to the new ones.
Documentation in English and a "Your first video" step
All public documentation now has an English version under /docs/en, with a language switcher and a separate search for each language. Get started has a new step, "Your first video", covering the SDK, the CLI and your agent.
YouTube: change a video that is already uploaded and still scheduled
PATCH /v1/posts/:id changes the publish time (at least 5 minutes ahead), title, description, tags, category and pinned comment of a video that Praeko already uploaded as private with a publish time. The server checks the video live before writing, and the response has itemResults per item; a video that is already public returns 409 video_not_private. On DELETE /v1/posts/:id, dismiss=true removes the publish time (the video stays private) and dismiss=true&delete_video=true deletes the video; without them, YouTube publishes it on schedule. In MCP, the update_post preview says what will change (will_change) and what cannot (cannot_change). See Publish a video.
New sign-in screen
The panel sign-in was redesigned: passkey as the main path, e-mail and password, second factor, and a recovery mode that signs in with the API key (the key stays in that tab only).
Invitations and Forgot password
People invited from the waitlist get an e-mail, in Portuguese or English, with a 7-day link to create their password. On the sign-in screen, Forgot password sends a single-use link valid for 1 hour; the response is always the same, whether the account exists or not. Saving the new password ends the person's other sessions.
Media served from praeko.app
Public media URLs (publicUrl) now use the praeko.app domain.
Instagram profile picture
An Instagram channel connected through the Meta API now gets the account's profile picture (at GET /v1/channels/instagram/avatar and in the panel). It is copied on connect, on Check now and every 3 days.
Notifications in the panel and by e-mail
The panel bell shows notifications for sent posts, failures, retries, the weekly summary and new YouTube comments, and lets you mark them as read. Through the API: GET /v1/notifications and POST /v1/notifications/read (notifications belong to a person, so with an API key the list is empty). By e-mail: the weekly summary on Mondays and new YouTube comments, at most one e-mail per hour. Each person chooses under Settings › Notifications; by default, no e-mails and panel notifications on. Notifications are kept for 30 days.
MCP: sign in with OAuth
Connectors that use OAuth (such as Claude.ai's) connect to https://praeko.app/mcp by signing in to Praeko, with no key to paste: the agent opens a consent screen and you manage the connections under API keys › Agent connections. An API key in the Authorization: Bearer header still works. See MCP server.
MCP: upload a local file
The create_media_upload, complete_media_upload and get_media tools (18 tools now) let an agent with a shell publish a video that is on disk: the server prepares the upload, the agent runs curl with the key from the environment and confirms. No confirmation code (nothing gets published), with limits on size, pending uploads and lifetime. See MCP server.
Panel in English
The panel screens now have an English version, including the messages for API error codes. Pick the language in Settings.
SDK and CLI on npm
@praeko/sdk 0.1.2 and @praeko/cli 0.1.1 are on npm, MIT-licensed, with the code at github.com/Praeko/praeko-js. The CLI has a single command, praeko, so npx @praeko/cli --help works. See SDK and CLI.
API address on praeko.app
The docs and examples use https://praeko.app as the base address. GET /health returns service: "praeko".
Public documentation at praeko.app/docs
A reference for every route, each with a sample response, success statuses and examples in 10 languages; guides, a page per AI agent, search, llms.txt and a Markdown copy of every page (append .md to the URL).
Remote MCP server
One address, https://praeko.app/mcp, for AI agents to read the docs; query channels, media, posts, the calendar, metrics and usage; and create, schedule, edit and cancel posts, upload media from a URL and create ideas. Creating, scheduling, editing and canceling posts, uploading media from a URL and creating ideas take two steps (preview and confirmation code). See MCP server.
Idempotency-Key header
Send Idempotency-Key on POST, PATCH and DELETE and a retry returns the first response, with Idempotent-Replayed: true, without creating anything new. The key lasts 24 hours. A key reused with a different request: 422 idempotency_key_reuse; a request still running: 409 idempotency_in_progress. The SDK gained the idempotencyKey option and the CLI the --idempotency-key flag. See Retry a request.
Retention, impressions and CTR
GET /v1/insights/retention and GET /v1/insights/:item/retention return the YouTube retention curve, impressions and CTR, plus Instagram reach and watch time. A number the network does not provide comes back as null, never 0. Instagram also gained reel skips, reposts, new followers and profile visits. The YouTube connection now asks for the Analytics permission: a channel connected before shows as reauthorize until you reconnect it. See Metrics, retention and CTR.
Passkeys
Sign in to the panel with a passkey (WebAuthn), using your device's biometrics or PIN. User verification is required, and you manage passkeys in Settings.
Preferences, theme and language
GET /v1/preferences and PUT /v1/preferences store the theme, the language and the e-mail and panel notification preferences (by default, no notification e-mails). The panel gained a light, dark or system theme and a Portuguese or English language setting.
Ideas on the server
The Create board no longer lives in the browser: GET, POST, PATCH and DELETE on /v1/ideas, plus POST /v1/ideas/import (up to 500 per call, safe to repeat). Columns idea, scripting, ready and posted. New errors: idea_not_found and idea_limit_reached. The SDK gained praeko.ideas.
Video duration and dimensions
Video media carries durationMs, width and height, read from the MP4 or MOV header. Older videos get the values on first read.
Outgoing webhooks
Register a URL at /v1/webhooks (admin scope) and receive post.sent, post.failed and post.scheduled-fail. Every delivery is HMAC-signed, with spaced-out retries and automatic deactivation of a webhook that keeps failing. Internal addresses are rejected. The SDK gained praeko.webhooks and the CLI praeko webhook. See Webhooks.
Usage and log
GET /v1/usage summarizes calls (total, errors, p95, peak per minute, per day and per key) and GET /v1/usage/log lists the requests of the last 30 days, metadata only. The CLI gained praeko usage and praeko usage log.
Posts created outside Praeko
What you publish directly on a network now shows up in Sent on its own, every 15 minutes per channel (YouTube, TikTok and Instagram), marked "Outside Praeko". GET /v1/content returns them with origin external. These posts do not trigger webhooks.
Per-item metrics with milestones
Each item in GET /v1/insights has postId, tags and milestones (views at milestones from 1 hour to 7 days, when recorded). It feeds the curve on the Analytics tab.
Multiple accounts per network
One workspace can connect more than one YouTube or TikTok account. Pick each item's account with the post's channel.
Praeko replaces Arauto
praeko_… keys instead of arauto_…, the praeko command and the PRAEKO_KEY variable; the header is now X-Praeko-Contract. Still accepted: arauto_… keys, the ARAUTO_CHAVE variable and the X-Arauto-Contract header. The old arauto command no longer exists in @praeko/cli.
Portuguese paths
The old paths still answer, with Deprecation: true and a Link header with rel="successor-version". A shutdown date has not been set yet.
Contract v1 in English
Send the en contract header (today X-Praeko-Contract: en) and use /v1/posts, /v1/insights and /v1/youtube/videos, with routes, fields, values and error codes in English. Portuguese fields are rejected under this contract. The SDK and the CLI already speak the new contract. See Authentication, errors and limits.