Annunciamo l'API AfiniTwin per integratori

Cinque endpoint REST autenticati con API key. Servi il tuo AfiniTwin come system prompt dal tuo CRM, assistente proprio o pipeline notturna. Incluso nel tuo abbonamento afini.ai. Oggi.

I. Il gesto minimo

L'AfiniTwin Portable si scarica dal dashboard da un paio di mesi. Funziona: copi il preset, lo incolli in Claude, ChatGPT o 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.

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 o qualsiasi altro, 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.

System prompt, def.: il modo in cui un LLM si ricorda di chi è prima di dimenticare chi sei tu. L'API B2B si occupa di preservargli la memoria di te.

II. 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 e 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 ogni AfiniTwin che il tuo abbonamento genera mese dopo mese. 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 diecimila richieste al mese, configurabile fino a un milione per key. Ogni risposta include header X-Twin-Quota-{Limit,Used,Remaining} perché la tua integrazione sappia quanto le rimane senza dover indovinare.

III. Perché API key, 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 API key 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.

API key, def.: segreto che mantiene la sua condizione di segreto esattamente tra la riga in cui viene generato e la prima volta in cui qualcuno, per distrazione, lo incolla in un repository pubblico. Per questo la revoca è rapida.

Le key sono segreti in senso forte: in database salviamo solo l'hash SHA-256, formato atk_live_<8 hex>_<32 hex>. Il plaintext si mostra una sola 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.

IV. Parte del tuo abbonamento

La generazione di key è inclusa nel tuo abbonamento afini.ai, sia tramite abbonamento Stripe attivo che tramite voucher vivo. Gli endpoint pubblici servono indistintamente, purché la tua key sia stata emessa su un account con abbonamento attivo. Se il tuo abbonamento si interrompe, le key restano salvate ma gli endpoint restituiscono 403 finché non lo riattivi. Non le cancelliamo: le lasciamo in pausa, in attesa.

L'API è una funzionalità in più dell'abbonamento, non un extra che si compra a parte. Le integrazioni B2B implicano carico sostenuto sulla nostra infrastruttura — lo snapshot vive nel nostro database, gli header arrivano dal nostro proxy — ed è già coperto dalla quota mensile. Nessuna clausola in piccolo: se sei abbonato, ce l'hai.

V. Quota e rate-limit: due cinture

La quota mensile misura volume aggregato. Il rate-limit per IP e per key misura raffiche. Oggi ti serviamo sessanta richieste al minuto su ogni endpoint pesante, centoventi 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.

Quota mensile, def.: pietà temporale che l'infrastruttura concede all'integratore distratto, espressa in request. Si rinnova il primo del mese; il due ricomincia la prova.

VI. 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.

VII. Come iniziare oggi

Abbonati o riscatta il tuo voucher su https://afini.ai/precios se non l'hai ancora fatto.
Genera il tuo AfiniTwin dal dashboard se non ce l'hai ancora. L'API funziona senza Twin — restituisce 403 NO_TWIN_PURCHASED —, ma senza Twin non c'è molto da servire.
Genera la tua prima key su https://afini.ai/it/dashboard/twin/api. Copiala nel vault della tua integrazione. Non committarla in un repo.
Chiama /v1/public/twin/health per verificare che sia viva. Non consuma quota.
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 un milione al mese, scope specifici, supporto SLA —, scrivi a info@afini.ai. C'è margine di negoziazione.

VIII. Roadmap onesta

Oggi (v1.0): i cinque endpoint sopra, scope unico twin:read, incluso nell'abbonamento afini.ai, quota configurabile fino a un milione.

Prossime settimane: webhook per notificarti 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