Caricare file sull'API di Claude: limiti, scadenza e la trappola del workspace

La Files API di Claude è l'endpoint che permette di caricare un documento una volta sola su /v1/files e poi richiamarlo per file_id in ogni richiesta successiva, invece di rispedirne il contenuto tutte le volte. Dal 19 agosto 2026 caricare file sull'API di Claude non richiede più l'header beta files-api-2025-04-14, perché Anthropic ha portato la Files API in disponibilità generale.

La parte interessante della disponibilità generale però non è l'etichetta che cade. È che togliere quell'header cambia il formato della risposta che il codice riceve indietro, e non c'è nessun avviso: la richiesta continua a funzionare, semplicemente restituisce campi diversi. Chi ha scritto la paginazione dell'elenco file un anno fa e la lascia lì se ne accorge quando si rompe, non prima.

Cosa è uscito dalla beta il 19 agosto 2026

Le release notes della piattaforma Claude datate 19 agosto 2026 portano in disponibilità generale tre pezzi diversi della Claude API nello stesso giorno, e per tutti e tre la conseguenza pratica è la stessa: l'header beta non serve più.

Anthropic precisa per tutte e tre le funzioni che le richieste che continuano a mandare l'header vengono accettate senza modifiche. Nessuno deve correre a togliere niente stanotte, e questo è il punto che rende la cosa più insidiosa di una rottura netta. Sulla Skills API, uscita dalla beta nella stessa tornata, il passo successivo è capire cosa mettere davvero dentro una skill: ne ho scritto in come trasformare un documento in una skill per Claude Code.

Nello stesso giorno Anthropic ha aggiunto ai Claude Managed Agents la possibilità di limitare i siti che gli strumenti web_search e web_fetch possono raggiungere, tramite i campi allowed_domains e blocked_domains. Se ti interessa il tema di quali confini dare a uno strumento che agisce da solo, ne ho scritto in quali permessi dare agli strumenti AI in azienda.

Perché togliere l'header beta cambia la risposta e non solo la stabilità

Togliere files-api-2025-04-14 da una chiamata alla Files API cambia il formato con cui l'endpoint di elenco pagina i risultati. Con l'header, la lista pagina con before_id e after_id e restituisce has_more, first_id e last_id, e rifiuta i parametri page e ids[] come campi sconosciuti. Senza l'header, la stessa lista restituisce un cursore next_page e accetta page e ids[].

La stessa rimozione dell'header cambia anche una cosa più piccola e più cattiva. Sotto l'header, un file senza scadenza non riporta affatto il campo expires_at. Senza header, lo stesso file riporta expires_at valorizzato a null. Un controllo scritto come if "expires_at" in file si comporta in due modi opposti nei due casi.

Cosa controllare prima di toglierlo

Gli SDK ufficiali e la CLI aggiungono l'header da soli sulle chiamate beta.files, quindi il codice che usa quei metodi sta ancora oggi nel formato vecchio anche se nessuno lo ha scritto a mano. Prima di passare al formato nuovo conviene cercare nel proprio codice tre cose: la lettura di has_more, first_id o last_id, l'uso di before_id e after_id, e ogni test di presenza sul campo expires_at.

Quali sono i limiti della Files API di Claude

I limiti della Files API adesso sono scritti nella documentazione con numeri precisi, ed è questo che permette di dimensionare un prodotto invece di sperare.

Superare uno dei limiti della Files API produce errori diversi, e vale la pena conoscerli in anticipo: un file oltre i 500 MB restituisce un 413, l'organizzazione che ha saturato il terabyte riceve un 400, e un file di testo più grande della finestra di contesto restituisce comunque un 400 anche se il caricamento era andato a buon fine.

Come proteggere i dati aziendali quando li carichi su un'AI

I file caricati sulla Files API sono visibili a tutto lo spazio di lavoro, non alla singola conversazione e non al singolo utente finale. Anthropic lo scrive come avvertimento esplicito nella documentazione: qualsiasi chiave API dello stesso workspace può leggere qualsiasi file caricato lì, e tutte le chiavi condividono il Default Workspace dell'organizzazione se non sono state assegnate a workspace separati.

Da questa visibilità di workspace discende una regola operativa secca per chi costruisce un prodotto multi utente. Un file_id non si accetta mai da chi usa l'applicazione, perché un identificativo arrivato dal browser permetterebbe a una persona di leggere il documento caricato da un'altra. La corrispondenza fra utenti e file sta nel database dell'applicazione, e la separazione vera si ottiene con un workspace per ogni cliente, fino a un massimo di cento per organizzazione.

La scadenza non è una cancellazione garantita

La scadenza di un file si imposta solo al momento del caricamento, con il campo expires_in_seconds, e non si può più cambiare dopo. Quando il file arriva alla sua expires_at, il download del contenuto restituisce 404 e una richiesta Messages che lo cita fallisce prima ancora dell'inferenza.

Anthropic è però onesta su cosa la scadenza non è: i metadati del file restano leggibili fino a trenta giorni dopo, e il contenuto può essere conservato per un periodo limitato per revisione di sicurezza prima della cancellazione definitiva. Per togliere davvero un documento in fretta serve DELETE /v1/files/{file_id}, che rimuove subito anche i metadati. Chi lavora su documenti che non devono restare da nessuna parte trova il ragionamento su dove tenerli in come portare l'AI dentro il gestionale aziendale e nella pagina di consulenza sull'AI applicata ai dati aziendali.

Quando conviene caricare un file e quando basta incollarlo

Gli articoli di questo blog nascono da una routine che sta in automazione-blog/cloud-agent/, e ogni mattina quella routine legge tre file di regole dentro .claude/skills/articolo/ e otto file di misurazioni dentro data/seo/. Nessuno di quei file passa dalla Files API: vengono letti da disco e incollati nel prompt come testo. Il più pesante, data/seo/volumi-keyword.json, sta a 288 KB, cioè meno di un millesimo del limite per singolo file.

Prima della frequenza di riuso c'è però una domanda che viene prima di tutte, cioè quali di quei file abbiano davvero motivo di uscire dal disco: è il ragionamento che ho fatto per intero in dove finiscono i dati dell'intelligenza artificiale e quanto costa deciderlo.

Il criterio che regge la scelta è la frequenza di riuso, non la dimensione. Un file va sulla Files API quando lo stesso identico contenuto viene richiamato da molte richieste diverse senza cambiare in mezzo, perché in quel caso caricarlo una volta sola toglie lavoro a ogni chiamata successiva. Un file va incollato nel prompt quando serve una volta sola, oppure quando cambia a ogni esecuzione: caricarlo aggiungerebbe un giro di rete, un identificativo da tracciare e un oggetto da cancellare, in cambio di niente.

Il caso che sposta l'ago sono i documenti degli utenti finali

I documenti degli utenti finali, cioè il PDF che una persona carica dentro il tuo prodotto, sono il caso in cui la Files API vince quasi sempre. Il caricamento una tantum evita di rispedire gli stessi megabyte a ogni domanda della stessa conversazione, e expires_in_seconds dà al documento una data di morte senza dover scrivere un lavoro di pulizia. La parte difficile resta quella di sempre, ed è a monte: quanto di quel PDF Claude riesce davvero a leggere, che è il problema di cui ho scritto in estrarre dati dai PDF aziendali e in tradurre un PDF mantenendo l'impaginazione.

Cosa vale davvero la disponibilità generale

La disponibilità generale, per come la leggo, vale meno come annuncio e più come permesso: un'azienda che vieta le beta in produzione adesso può dire di sì a file e skill sull'API di Claude, e la Skills API uscita dalla beta lo stesso giorno sposta più peso di quanto sembri, per i motivi che ho spiegato in cosa sono le agent skills e come si installano. Il prezzo da pagare è una mezz'ora di lettura del proprio codice prima di togliere l'header, che è pochissimo rispetto a scoprirlo in produzione. La fonte è la pagina delle release notes della piattaforma Claude, e i limiti stanno tutti nella documentazione della Files API.