L'AfiniTwin Portable si scarica dal dashboard da un paio di mesi. Funziona: copi il preset, lo incolli in Claude/ChatGPT/Gemini, e l'IA parla con te come se ti conoscesse dal primo turno. Ma copia-e-incolla non scala. Se la tua integrazione B2B è seria — un CRM, un assistente proprio, una pipeline notturna di elaborazione —, ti serve qualcos'altro: che l'AfiniTwin entri da solo, programmaticamente, in ogni chiamata che il tuo sistema fa al LLM.

È quello che rilasciamo oggi. Un'API REST autenticata che serve il tuo AfiniTwin come system prompt, pronta per essere iniettata dal codice che stai scrivendo.

Il gesto minimo

Una key, una chiamata:

curl -H "X-Twin-Key: atk_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" \
  "https://api.afini.ai/v1/public/twin/preset/estandar?format=json&lang=it"

Restituisce il meta-prompt completo del preset richiesto, nel formato richiesto. Lo carichi come system nel tuo client Anthropic / OpenAI / Mistral / qualsiasi, e da lì in poi ogni turno è calibrato sul tuo profilo cognitivo. Senza riaddestramento. Senza fine-tuning. Senza passare per la nostra infrastruttura oltre la lettura iniziale dello snapshot.

Cinque endpoint, una sola idea

/v1/public/twin/health — un ping per validare che la key è viva senza spendere quota mensile. Per i tuoi health check di deployment.

/v1/public/twin/me — identità della key, piano del proprietario, quota usata/rimanente, ultimo Twin disponibile. Quello che chiamerai all'avvio della tua integrazione per rilevare un downgrade di piano o una key revocata.

/v1/public/twin/historic — listing dei tuoi snapshot (uno per acquisto AfiniTwin o per trimestrale gratuito del piano Professionale). Utile se la tua integrazione vuole far scegliere all'utente tra più.

/v1/public/twin/snapshots/:id — metadati di uno snapshot specifico.

/v1/public/twin/preset/:slug?format=...&lang=...&variant=...&includeNarratives=... — l'endpoint con sostanza. Restituisce l'artefatto in .txt, .md, .json o .yaml, in sei lingue, con o senza narrative Opus integrate.

Tutti gli endpoint tranne /health contano per la quota mensile. Default 10.000 richieste/mese, configurabile fino a 1 milione per key. Ogni risposta include header X-Twin-Quota-{Limit,Used,Remaining} perché la tua integrazione sappia quanto le rimane.

Perché key API, non OAuth

OAuth avrebbe senso se l'integrazione fosse un terzo che accede al profilo di un utente diverso. Non è il caso. L'API B2B serve il TUO AfiniTwin alla TUA integrazione — il tuo CRM, il tuo assistente, il tuo agente. Una key API personale, generata nel tuo dashboard, copiata nel vault della tua integrazione, è il modello che meglio si adatta: zero attrito di consenso, revoca istantanea, una key per integrazione perché il blast radius di una fuga sia limitato.

Le key sono segreti in senso forte: in DB salviamo solo l'hash SHA-256 (formato atk_live_<8 hex>_<32 hex>). Il plaintext si mostra solo una volta alla creazione. Se lo perdi, revoca e creane un'altra. Se pubblichi la key per sbaglio in un repo pubblico — capita, non sei il primo — revochi dal dashboard e va offline in millisecondi.

Piano Professionale, non per capriccio

La generazione di key è riservata al piano Professionale (abbonamento Stripe attivo o voucher Professionale vivo). Gli endpoint pubblici servono indistintamente, purché la tua key sia stata emessa su un account Professionale al momento del riscatto. Se scendi di piano, le key restano salvate ma gli endpoint restituiscono 403 finché non torni a Professionale. Non le cancelliamo: le lasciamo in pausa.

Perché non Esencial o Premium? Perché le integrazioni B2B implicano carico sostenuto sulla nostra infrastruttura (lo snapshot vive nel nostro DB, gli header arrivano dal nostro proxy), e il costo marginale per integrazione torna solo a prezzo Professionale. Non restrizione artificiale: ingegneria onesta.

Quota, rate-limit, due cinture

La quota mensile misura volume aggregato. Il rate-limit per IP/key misura raffiche. Oggi ti serviamo 60 richieste al minuto su ogni endpoint pesante, 120 al minuto su /health. Se la tua integrazione cade in un loop infinito accidentale, il rate-limit la cattura prima che ti svuoti la quota mensile. Non un solo strato di difesa.

Cosa NON siamo

Questo non è un endpoint «portami il profilo dell'utente X» dove X è qualcuno diverso dal titolare della key. La key autentica il proprietario e restituisce sempre il SUO AfiniTwin. Niente percorsi multi-tenant. Niente admin remoto.

Questo non è nemmeno un endpoint per addestrare modelli a spese dell'utente. Quello che serviamo è quello che è già nel suo snapshot immutabile. Se il nostro provider di inferenza (Anthropic) cambia la sua policy di ritenzione, non influisce retroattivamente sugli snapshot già generati.

E questo non è un sostituto del journaling, del coaching o della terapia. È un componente tecnico per integratori. Le questioni umane restano umane.

Come iniziare oggi

1. Abbonati o riscatta voucher Professionale su https://afini.ai/precios se ancora non l'hai.
2. Compra il tuo AfiniTwin dal dashboard se non l'hai già fatto. L'API funziona senza Twin (restituisce 403 NO_TWIN_PURCHASED), ma senza Twin non c'è molto da servire.
3. Genera la tua prima key su https://afini.ai/it/dashboard/twin/api. Copiala nel vault della tua integrazione. NON committarla in un repo.
4. Chiama /v1/public/twin/health per verificare che sia viva. Non consuma quota.
5. Leggi la documentazione completa su https://afini.ai/it/afinitwin/api. Esempi cURL, Node.js e Python, tabella completa degli errori, raccomandazioni di sicurezza.

Se il tuo caso di integrazione ha esigenze particolari — quote superiori a 1M/mese, scope specifici, supporto SLA —, scrivi a info@afini.ai. C'è margine di negoziazione.

Roadmap onesta

Oggi (v1.0): i 5 endpoint sopra, scope unico twin:read, piano Professionale, quota configurabile fino a 1M.

Prossime settimane: webhook (ti notificheremo quando un nuovo snapshot è ready, senza polling), scope twin:write per integrazioni che vogliano seminare fatti vitali (con consenso esplicito), metriche di utilizzo dal dashboard.

Quando servirà: SDK ufficiale in TypeScript e Python, esempi canonici di integrazione con Anthropic e OpenAI, piano Enterprise con SLA e quote oltre il milione.

Non promettiamo quello che non c'è. Se ti serve e non c'è ancora, dillo e si prioritizza.

— Ricardo