Changelog
New features, changes, and fixes in Puter.js and the Puter APIs, grouped by day, newest first.
November 2026
November 16, 2026
- Addedthe
backgroundoption toputer.notifications.enable(). It turns pushes back on without a click, such as on page load, and never opens a prompt, dialog, or sign-in window. See Calls without a click. - Added
puter.hosting.detach(), which opens a Puter dialog where the user removes custom domains from one of their websites. - Addedthe
custom_domainsfield to theSubdomainobjects fromputer.hosting.get()andputer.hosting.list(). Also addedpreviousSiteto theCustomDomainfromputer.hosting.attach(), for when the user moved the domain from another of their websites. - Addedthe
drainevent toputer.net.Socketandputer.net.tls.TLSSocket. It fires once the data written before the socket opened has been sent. - Fixed
puter.net.Socketandputer.net.tls.TLSSocketclosing with an error when adatahandler threw. Also fixedoff()on aputer.net.tls.TLSSocketnot removingopen,data, orclosehandlers. - FixedNode.js scripts that use Puter.js not exiting after their work finished.
November 15, 2026
- Fixed
puter.workers.create()failing with a server error for a worker name longer than 50 characters, or when another user owns the worker'ssandbox-<workerName>app. It rejects withbad_requestorsandbox_not_ownedinstead. - Changed
puter.workers.delete()to also delete the worker'ssandbox-<workerName>app, unless another worker still runs as it. A worker you create later with the same name starts with empty key-value data and an empty AppData folder.
November 14, 2026
- Changed
puter.ai.chat()so a request that a Claude model declines runs again on an earlier Claude model, and later calls in the same conversation stay on the model that answered. To get the refusal instead, passrefusalFallback: false. See Refusal fallback. - Addedthe
speedoption toputer.ai.chat()for Claude models. Set it to"fast"for Fast mode or"standard"for standard inference. See Anthropic models. - Added
puterIdto every model thatputer.ai.listModels()returns. It holds the full<service>:<provider>/<model>name, whichputer.ai.chat()accepts asmodel. - Changedthe
mistral-large-latest,mistral-large, andmistralai/mistral-large-latestmodel names inputer.ai.chat()to point to Mistral Large 4 instead of Mistral Large 3. - Changedthe AI concurrent request limit so a chat request you stop keeps counting until the model finishes. Sending new requests right after stopping a few can hit the limit. See Rate Limits and Quotas.
- Changed
puter.ai.txt2img()on Replicate models to try again when the model's safety checker rejects the image and you didn't set aseed. Only the run that succeeds is charged. See Replicate models. - Fixedapps opened from the Puter desktop at desktop.puter.com not getting messages from the desktop. Their windows didn't close, and
puter.ui.onWindowClose(),puter.ui.onItemsOpened(), and thelocaleChangedevent ofputer.ui.on()didn't fire.
November 13, 2026
- Fixed
puter.kv.set()failing with a server error when a value under the size limit takes more than 400 KB once stored. It rejects withvalue_too_large. - FixedURLs from
puter.fs.getReadURL()sometimes failing right after the call resolved, and sending an invalidContent-Typefor a file with no known extension, such asREADME. - Fixed
puter.fs.write(),puter.fs.copy(), andputer.fs.move()replacing an item whose name differs from the new name only by accents or emoji, such as😀.txtand😁.txt. The call keeps the existing item and rejects, unless you setdedupeName: true. - Fixed
puter.fs.write()not overwriting a file in place when the new name differs from the existing name only in letter case or Unicode normalization, such asnotes.txtandNotes.txt. - Fixed
puter.auth.getMonthlyUsage()andputer.auth.getDetailedAppUsage()resolving to the server's error body when the request failed. They reject with an error that hasstatusandmessage. - Fixed
puter.auth.signIn()on a cross-origin isolated page sometimes not finishing after the user signed in, and rejecting withauth_timeout. - Fixedapps opened on a file inside a folder shared with the user, such as a file from
puter.ui.onLaunchedWithItems(), not being able to read or save that file. - Fixed
puter.ui.showSaveFilePicker()withtype: 'url'not saving the URL's contents. See Saving from a URL. - Fixedqueued events from
puter.events.onPersistent()going to the events worker while a client with thehandlerfunction was still running them. A queued event goes only to clients that run its handler. - Changedthe Puter desktop to ignore a push permission your app got only through
puter.notifications.enable()on your website. In Puter apps,requestPermission()andenablePush()show Puter's permission dialog for it, andstatus()resolves to'off'until the user allows it there.
November 12, 2026
- Addedthe
failedarray to the result ofputer.fs.unshare(). It lists each recipient and item pair that was refused, with itsmessageandcode. When every pair is refused, the call rejects with{ message, code, failed }, unless every refusal wasuser_does_not_existorsubject_does_not_exist. - Changed
puter.ui.showColorPicker()in Puter apps to resolve to a lowercase 6-digit hex string, such as#ff0000, or tonullif the user closes the picker. Before, it resolved to an 8-digit hex string with alpha, or toundefined. On websites, it also opens when the default color has alpha or isn't a valid hex color. - Removedthe
themeChangedevent ofputer.ui.on(). It has no replacement, and a handler for it never runs. - Deprecatedthe
show_in_taskbaroption ofputer.ui.createWindow(). It has no effect, because the Puter desktop doesn't have a taskbar anymore.
November 11, 2026
- Changed
puter.ai.speech2speech()to reject anymodelother thaneleven_multilingual_sts_v2oreleven_english_sts_v2with afield_invaliderror.
November 10, 2026
- Fixeda file becoming unreadable when two
puter.fs.write()calls created the same new file at the same time. The last write wins.
November 9, 2026
- Addedthe
serviceSpeedoption toputer.ai.chat()to ask for"standard","fast", or"ultrafast"service. Faster service can cost more, andusageDetails.serviceSpeedreports the speed that served the request. See Service speed.
November 7, 2026
- Renamed
puter.ai.convo()toputer.ai.realtime()(beta). It takes the same options, and theConvo*TypeScript types are nowRealtime*types, such asRealtimeOptions. Calls toputer.ai.convo()throw, so switch them toputer.ai.realtime().
November 6, 2026
- Changed
puter.notifications.enable()on a website to show a Puter dialog when it isn't called from a click, or when the click has expired, such as after a sign-in window. The browser's prompt opens from the dialog's Continue button, and Cancel resolves tofalse. Before, the call rejected withuser_gesture_required.
November 5, 2026
- Added
puter.notifications.markShown()andputer.notifications.dismiss(), so the next notification with the samegroupcreates a new one instead of replacing it. A dismissal also closes the notification on the user's other devices, and fires thedismissevent ofputer.notifications.on(). - Added
priority: 'high'toputer.notifications.notify()for pushes that need to arrive right away, such as an incoming call. - Added
requireInteractionandactionsto what anonPush()handler can return, so a push can stay on screen and show buttons. The id of the pressed button reaches theclickevent ofputer.notifications.on()asaction. - Added
puter.events.updateSchedule()(beta) to change a schedule's timing or context, or a notification stored withsendAt, without changing its id. - Removednotifications shown by the page itself. A page of your website in the background no longer shows a notification from your
onPush()handler. Puter pushes it to every browser where the user turned pushes on, unless a page of your app is visible and focused when it arrives. See When a notification is pushed. - Addedthe
prompt_cache_optionsoption toputer.ai.chat()for GPT-5.6 and later OpenAI models. It sets a 30 minute or 12 hour cache lifetime. - Changed
usageDetailsfromputer.ai.chat()on OpenAI models to report cache writes ascacheWrite30mTokensandcacheWrite12hTokensinstead ofcacheWrite5mTokens. See ChatResponse. - Changedthe default model of
puter.ai.txt2img()fromgpt-image-2togpt-image-2.6-flare. To keep the old model, passmodel: 'gpt-image-2'. - Addedthe
context_trimmedevent toputer.ai.convo(). It fires after a reconnect when older items were left out of the restored context. Before, that case fired anerrorevent withcontext_restore_failed. - Changed
interrupt()on aputer.ai.convo()conversation to return a promise that rejects withsession_not_readyorsession_closedinstead of throwing when the conversation isn't ready. Also changedconnect()to retry temporary setup failures before it rejects. - Fixed
puter.ai.convo()ending the conversation when the server sent an event over 64 KiB, and its microphone capture stopping after a reconnect. - Changedthe Realtime WebSocket API to close with code 1011 and an
internal_errorwhen a server error stops Puter from checking your credential or plan, instead ofinvalid_api_keywith code 1008. It closes with 1013 when the server is overloaded. Reconnect after 1011, 1012, or 1013. - Addedthe
purpose=handoverquery parameter to the Realtime WebSocket API for opening a replacement connection while the current one still works. - Fixedinput transcription on the Realtime WebSocket API failing to turn on for users with little credit.
November 4, 2026
- Addedinline handlers to
puter.events.onSchedule()andputer.events.onPersistent()(beta). Pass your code ashandlerwithout ahandlerName, and Puter publishes it in the signed-in user's own user scope. - Addedthe
scope: 'user'option toputer.events.handlers, and thehandlerScopeoption toonSchedule()andonPersistent(), so a user's session can publish named handlers in its own scope and bind to them. - Addedthe
fromoption toputer.events.fetch()(beta). Withfrom: 'end', a read without a cursor returns no items and a cursor at the newest notification, so later reads return only newer notifications. - Added
puterPush.savedHandlers()for the push service worker. Call it withfalseto run only the handlers registered in the worker, never the handler source your pages saved withonPush(). - Fixedthe
off()function fromonPush()removing the saved handler while another tab still used it, and pages with a push handler being kept out of the browser's back/forward cache. - Fixed
puter.notifications.enable()rejecting withpush_subscription_conflictfor a subscription Puter made earlier with an older key, and pushes stopping after the browser replaced its subscription. - Fixednotifications sent from a website that uses Puter.js naming the app by its uid. The notification's
app.nameis the site's hostname.
November 3, 2026
- Addedschedules to the Events API (beta). A handler can run at an interval, on a cron expression, or once at a set time, even while your app is closed. Create one with
puter.events.onSchedule(), and manage them withlistSchedules(),getSchedule(), andremoveSchedule(). - Addedthe
sendAtoption toputer.notifications.notify()to send a notification at a set time, andputer.notifications.cancel()to cancel it before it goes out. With asendAtmore than 5 seconds ahead,notify()resolves to{ scheduleId, sendAt }instead of a notificationuid. - Changed
puter.auth.signOut()to return aPromise. On a website, it also ends this browser's push subscription for your app, and so does a different user signing in. - Fixed
puter.notifications.disable()ending a push subscription that another service, such as Firebase, made on your site. Only the subscription Puter made is removed. - Fixed
puter.notifications.onPush()opening the Puter sign-in window when it renewed the subscription on page load, and other tabs subscribing again afterdisable()ran in one tab. - Fixedtaps on push notifications on a website. A tap opens one page, once, and a tap without a URL opens your site's root, or your service worker's folder when your pages are inside it.
- Fixed
puter.ui.showFontPicker()in Puter apps ignoring the default font, and failing when given a font name as a string.
November 2, 2026
- Changed
puter.notifications.status()on a website to check this browser's subscription with Puter. It resolves to'off'after the user removes this browser or turns your app off in Puter's settings, and page loads don't turn pushes back on in that browser until your page callsenable(). - Fixedthree Workers router responses. A 404 for an unmatched path or method has the CORS header, a
fetch()response returned by a handler is sent instead of becoming a 500, and a Puter.js error thrown in a handler comes back as JSON in the 500 body. - Fixed
puter.kvwrites rejecting some values overMAX_VALUE_SIZEwithbad_request. Every value over the limit rejects withvalue_too_large.
October 2026
October 31, 2026
- Addedthe
fallbackoption toputer.ai.chat(). Passfalseto get the first provider's error, instead of having Puter retry the request on another provider that serves the same model. - Changedhow
puter.ai.convo()reconnects. It keeps trying for about a minute, restores up to 40 recent conversation items, and moves to a new session before a planned server restart. - Addedthe
puter.reconnectevent to the Realtime WebSocket API. Puter sends it before the server a session runs on restarts, so your client can move to a new connection first. - Changedrealtime sessions to refuse
conversation.item.retrieveevents and MCP tools with aninvalid_eventerror and a 1008 close. - Changed
puter.notifications.notify()so a notification reaches only the app that sent it. The Puter desktop's notifications panel doesn't show it. - Changedthe
groupoption ofnotify()to replace the newest notification your app sent the user in that group, unless that one was shown or dismissed. The replacement keeps the sameuid, andonNotification()gets it again withreplaced: true. Agroupcan be up to 128 characters and contain@. - Added
puter.notifications.status(), which tells you whether your app's pushes reach the user's current browser, without prompting the user. - Addedthe
notifyoption toputer.kv.share()and thetooption tonotify(), so the owner and the holder of a share can send each other notifications. Thekv.share.receivednotification only goes out for shares made withnotify: true. - Addedthe
'pushNotifications'resource toputer.perms.request(), so you can ask for push permission in the same prompt as other access. - Changed
puter.notifications.enable()on a website to resolve once the browser has subscribed, without waiting for the confirmation push. - Changed
enable()andenablePush()in Puter apps to show Puter's permission dialog when your app doesn't have push permission yet. In Puter apps,disable()removes your app's push permission. - Changeda
'kvShare'request inputer.perms.request()to ask for'read'access whenaccessis left out, the same default asputer.kv.share(). - Addeda rate limit on calls through share handles into one user's data for one app. Calls over it reject with
too_many_requests. See Rate Limits and Quotas. - Changed
puter.kv.share()so a call that changes nothing for any recipient doesn't count toward the share limits. Your app can call it each time it opens to get thehandleback. - Changed
puter.events.onLocal()subscriptions through a share handle to end withsubscription_endedwhen the share stops. Key-value events through awatchshare leave out the value, even withincludeValue. - Added
puter.events.update()(beta) to change a persistent subscription'scontextwithout ending it. The subscription keeps itssubIdand the events it hasn't delivered yet. - Changedthe events worker to retry a handler run that fails because of Puter, such as a
5xxerror, without counting it toward the failures that suspend a subscription. - Added
app_uidandapp_nameto theWorkerDeploymentobject fromputer.workers.create(), andapp_nameto theWorkerInfoobject. They name the app the worker runs as. - Added
dnsProviderandredirectFromto theCustomDomainobject. When a root domain's DNS is on Route 53 or GoDaddy, the domain is added as itswww.hostname, and anArecord with the purposeredirectforwards the root domain to it.
October 30, 2026
- Added
puter.ai.convo()(beta) for realtime voice and text conversations with OpenAI's realtime models. It has helpers for the microphone, playback, and interruptions, and needs a paid Puter plan. - Addedthe Realtime WebSocket API (beta) to use the same realtime models through Puter without Puter.js.
- Changed
puter.notifications.notify()to push a notification only when no open page of your app answers within 5 seconds that it's visible and focused, or that it shows the notification itself. See When a notification is pushed. - Changedpush opt-in on websites to stay off until your page turns it on. On page loads,
onPush()keeps a browser subscribed only afterenable(), and stops afterdisable(), after the user turns your app off in Puter, or afterputer.auth.signOut(). - Addedthe
push_worker_conflict,push_subscription_conflict,push_subscribe_failed, anduser_gesture_requirederrors toputer.notifications.enable(), and theinvalid_handlererror toonPush(). - Changedthe push service worker script to load from
https://js.puter.com/push-sw.js. The oldhttps://js.puter.com/v2/push-sw.jsURL still works. - Fixed
puter.auth.signIn(),puter.perms.request(), and other calls that open a Puter popup showing nothing when the browser blocked the popup, such as in Safari and iPhone Home Screen web apps. They show a Continue dialog instead.
October 29, 2026
- Addedthe Notifications API. Your app can send its user notifications with
puter.notifications.notify(), receive them live withonNotification(), and, with the user's permission, send them as push notifications to their browser or phone. See Push notifications for your app.
October 28, 2026
- Addedthe
queueoption toputer.events.onPersistent()(beta) in place ofdelivery: 'single', which still works. Subscriptions reportqueueinstead ofdeliveryandtargets. - Changed
onPersistent()subscriptions withoutqueueto run the handler in your app's events worker and also send each event to every connected client. Before, each event went to only one of the two. Thetargetsoption is ignored. - Changedqueued deliveries to drop the event when the handler throws, instead of retrying it. Temporary errors and errors thrown with
retry: trueare still retried, and a connected client has 15 seconds to answer before the events worker takes the event. See What happens when a handler fails. - Fixed
puter.net.Socketsending writes made right after it connects out of order, and treating anopenlistener that throws as a failed connection. - Changed
puter.ai.speech2txt()on OpenAI models to ignoreresponse_formatandstreaminextra_body. Setresponse_formatas a top-level option instead.
October 27, 2026
- Added
puter.hosting.attach(), which opens a Puter dialog where the user connects a domain they own to one of their websites. It resolves to aCustomDomainobject, or tonullif the user closes the dialog. - Fixed
puter.perms.request()for the'subdomains'resource having no effect. With read access,puter.hosting.list()andputer.hosting.get()cover all of the user's websites, and write access addsputer.hosting.update()andputer.hosting.delete(). - Fixed
puter.ui.launchApp()never settling when the Puter desktop can't launch the app. It rejects withipc_handler_failed. - Changed
puter.fs.listShared()to mark items shared with one of your teams withholderTeam. Leaving an item you only have through a team withputer.fs.unshare()rejects withteam_share. - Fixed
puter.fs.readdir()ignoringoffsetwhenrecursiveistrue. Also fixedputer.fs.copy()onto an existing file, which replaces the file whenoverwriteistrueand rejects otherwise.
October 26, 2026
- Addedsharing with up to 50 users in one
puter.kv.share()call (beta). Pass an array of recipients, and the call resolves to one result per recipient. - Addedthe
appUidoption toputer.kv.listShared()andputer.kv.listSharedByMe(), and thestateoption tolistSharedByMe()to list only live or only stopped shares. Stopped shares are kept for 30 days. - Changed
watchshares so the holder can list keys, without their values, withputer.kv.list(). - ChangedKimi K3 in
puter.ai.chat()to report the prompt tokens written to its cache ascache_write_tokensinusage, separate fromprompt_tokens. - Fixed
puter.ai.chat()encoding a tool call'sargumentstwice when you sent an assistant message withtool_callsback to a model served through an OpenAI-compatible API.
October 25, 2026
- Addedkey-value sharing (beta). A user can share the keys under a prefix with another Puter user at
watch,read, orwriteaccess withputer.kv.share(), and the other user passes the share'shandleto theputer.kvmethods. Manage shares withunshare(),listShared(), andlistSharedByMe(). - Addedthe
onlyIfAbsentoption toputer.kv.set(). It writes the key only when the key has no live entry, and resolves tofalseotherwise. - Addedthe
'fs','backgroundEvents', and'kvShare'resources toputer.perms.request()andputer.perms.check(), with theputer.perms.Resource,puter.perms.Access, andputer.perms.Folderconstants. The'permission'resource and raw permission strings are deprecated. - Fixed
puter.perms.check()returningfalsefor a file inside a folder your app already has access to, which madeputer.perms.request()prompt again. - Addedthe
viaWorkerfield to filesystem and key-value events. It'struewhen server-side code running as the account, such as a worker, made the change.
October 23, 2026
- FixedPuter.js calls made with an expired session rejecting with
Unauthorizedeven after the user signed in again. Puter.js retries the call once with the new session.
October 22, 2026
- Changedhow a stopped
puter.ai.chat()stream is billed. Once the request reaches the model, the model finishes its response and the whole response is billed, even if you break out of the stream or abort it with anAbortSignal. - Fixed
puter.workers.delete()removing the worker when Puter couldn't take its script down, and rejecting when the script was already gone. A call that fails keeps the worker, so you can call it again.
October 21, 2026
- Fixed
puter.fs.read()ignoring theoffsetandbyte_countoptions. Withoutbyte_count, the read goes fromoffsetto the end of the file. - Fixed
puter.auth.signIn()calls made at the same time sharing one sign-in window. Each call opens its own window and completes from it.
October 20, 2026
- Addedthe
inputVideooption toputer.ai.txt2vid()to edit a video you supply, with the prompt describing the change. See Video input. - Added
Blob,File, and Puter file paths as image inputs toputer.ai.txt2img()andputer.ai.txt2vid(). Puter.js uploads aBlob, aFile, or adata:URI over 1 MiB to a temporary file in the user's storage for the length of the call. - Fixed
isDirbeingfalsefor a folder your app is opened with, in theFSItemobjects thatputer.ui.onLaunchedWithItems()passes to your handler.
October 19, 2026
- FixedGemini text-to-speech in
puter.ai.txt2speech()failing on audio longer than about 65 seconds. - Fixed
getAuthToken()in Node.js leaving its local sign-in server running after the user signed in. The call rejects when it can't open the browser.
October 17, 2026
- Fixed
puter.ui.showOpenFilePicker(),puter.ui.showSaveFilePicker(), andputer.ui.showDirectoryPicker()on websites resolving with a message object when the user cancels. The promise stays pending, andshowDirectoryPicker()gets the sameundefinedOnCancelpromise as the file pickers, which resolves toundefined. - FixedGemini text-to-speech in
puter.ai.txt2speech()reading theinstructionsaloud along with the text. Gemini uses them only to guide the delivery, and they can be up to 3,000 characters. - FixedGemini function calling in
puter.ai.chat()dropping the thought signature inextra_contentwhen you send an assistant message'stool_callsback. - RemovedOpenRouter's
:batchmodel variants fromputer.ai.listModels(). Use the model id without the:batchsuffix.