API B2B AfiniTwin

API REST autenticata per accedere programmaticamente all'AfiniTwin Portable di un utente e servirlo come system prompt in CRM, assistenti propri o pipeline IA. Pensata per integratori B2B.

Autenticazione

Ogni chiamata richiede l'header X-Twin-Key (o Authorization: Bearer atk_live_...). Il plaintext si consegna una sola volta alla creazione della key; nel DB si salva solo il suo hash SHA-256. Se perdi il plaintext, revoca la key e creane un'altra.

curl -H "X-Twin-Key: atk_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" \
  https://api.afini.ai/v1/public/twin/me

Endpoint

Health check (non consuma quota)

Restituisce {ok: true, apiKeyId, userId, scopes, serverTime}. Utile per verificare che la key sia viva senza spendere quota.

GET /v1/public/twin/health

Identità e quota

Restituisce il piano del proprietario, gli scope della key, la quota mensile usata/rimanente e l'AfiniTwin più recente in stato ready.

GET /v1/public/twin/me

Listing di snapshot

Tutti gli AfiniTwin del proprietario con data, versione, fonte e stato. Utile per integratori che vogliono mostrare opzioni all'utente.

GET /v1/public/twin/historic

Metadati di uno snapshot

Informazioni su uno snapshot (NON include il PCP completo — quello passa per /preset/:slug). Utile per mostrare metadati o decidere se riutilizzarne uno vecchio.

GET /v1/public/twin/snapshots/:id

Scaricare artefatto

Restituisce l'artefatto del preset scelto nel formato richiesto, pronto da iniettare come system prompt. Accetta gli stessi query params della versione web. Ogni chiamata conta per la quota mensile.

GET /v1/public/twin/preset/:slug?format=txt|md|json|yaml&lang=es|en|fr|de|it|pt&variant=claude|gpt|gemini|generic&includeNarratives=true|false&purchaseId=...

Quote e limiti

Ogni key ha quota mensile configurabile (default 10.000 req/mese, max 1.000.000). Le quote si resettano il 1° di ogni mese UTC.

• Header X-Twin-Quota-{Limit,Used,Remaining} in ogni risposta indicano lo stato attuale.
• L'endpoint /health non consuma quota: usalo per verificare la key senza spendere.
• Quota esaurita → 429 con campo resetsAt in ISO UTC.

Codici di errore

Tutte le risposte di errore seguono la struttura { error: { type, code, message, ... } }.

• 401 MISSING_API_KEY — nessun header X-Twin-Key né Authorization Bearer inviato.
• 401 INVALID_API_KEY_FORMAT — la key non corrisponde al formato atk_live_<8 hex>_<32 hex>.
• 401 INVALID_OR_REVOKED_API_KEY — la key non esiste, è stata revocata o è scaduta.
• 403 FORBIDDEN MISSING_SCOPE — alla key manca lo scope richiesto per l'endpoint.
• 403 NO_TWIN_PURCHASED — il proprietario non ha ancora acquistato nessun AfiniTwin.
• 425 TWIN_NOT_READY — l'AfiniTwin è in generazione (status pending o generating). Riprova in 30s.
• 429 MONTHLY_QUOTA_EXCEEDED — quota mensile esaurita. Reset il 1° del mese successivo UTC.

Esempi di integrazione

JavaScript / Node

const TWIN_KEY = process.env.AFINI_TWIN_KEY;
const r = await fetch('https://api.afini.ai/v1/public/twin/preset/estandar?format=json&lang=es', {
  headers: { 'X-Twin-Key': TWIN_KEY },
});
const systemPrompt = await r.text();
// inject systemPrompt into your LLM call

Python

import os, requests
TWIN_KEY = os.environ['AFINI_TWIN_KEY']
r = requests.get(
    'https://api.afini.ai/v1/public/twin/preset/estandar',
    params={'format': 'json', 'lang': 'es'},
    headers={'X-Twin-Key': TWIN_KEY},
    timeout=30,
)
r.raise_for_status()
system_prompt = r.text

cURL — pipeline shell

#!/bin/bash
TWIN_KEY="atk_live_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"

# Validar que la key sigue viva (no consume cuota)
curl -fsS -H "X-Twin-Key: $TWIN_KEY" \
  https://api.afini.ai/v1/public/twin/health > /dev/null

# Bajar JSON del Twin para inyectar en agente
curl -fsS -H "X-Twin-Key: $TWIN_KEY" \
  "https://api.afini.ai/v1/public/twin/preset/estandar?format=json&lang=es" \
  -o twin.json

Sicurezza

• Le key sono segreti. Non pubblicarle mai in repository, frontend o endpoint accessibili dall'esterno.
• Una key revocata smette di funzionare all'istante. La tua integrazione deve reagire al 401 INVALID_OR_REVOKED_API_KEY ruotando la key.
• Se scendi dal piano Professionale, le key restano salvate ma gli endpoint restituiscono 403 fino a che non torni a Professionale.
• Per privacy, non accettiamo integrazioni che inoltrino il PCP di un utente a sistemi che non ha autorizzato. La responsabilità ricade su chi usa la key.

Changelog

• v1.0 (2026-05-10): Lancio. 5 endpoint pubblici (health, me, historic, snapshots/:id, preset/:slug). Singolo scope twin:read. Quota mensile configurabile per key.

tuo dashboard →