API B2B AfiniTwin

API REST authentifiée pour accéder programmatiquement à l'AfiniTwin Portable d'un utilisateur et le servir comme system prompt dans des CRM, assistants propres ou pipelines d'IA. Conçue pour les intégrateurs B2B.

Authentification

Chaque appel nécessite l'en-tête X-Twin-Key (ou Authorization: Bearer atk_live_...). Le plaintext est livré une seule fois à la création de la clé ; la BD ne stocke que son hash SHA-256. Si tu perds le plaintext, révoque la clé et crée-en une autre.

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

Endpoints

Health check (ne consomme pas de quota)

Renvoie {ok: true, apiKeyId, userId, scopes, serverTime}. Utile pour vérifier que la clé est vivante sans dépenser de quota.

GET /v1/public/twin/health

Identité et quota

Renvoie le plan du propriétaire, les scopes de la clé, le quota mensuel utilisé/restant, et l'AfiniTwin le plus récent à l'état ready.

GET /v1/public/twin/me

Listing de snapshots

Tous les AfiniTwins du propriétaire avec date, version, source et statut. Utile pour les intégrateurs qui veulent lister des options à l'utilisateur.

GET /v1/public/twin/historic

Métadonnées d'un snapshot

Informations sur un snapshot (n'inclut PAS le PCP complet — ça passe par /preset/:slug). Utile pour afficher des métadonnées ou décider si réutiliser un ancien.

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

Télécharger un artefact

Renvoie l'artefact du preset choisi dans le format demandé, prêt à injecter comme system prompt. Accepte les mêmes query params que la version web. Chaque appel compte pour le quota mensuel.

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

Quotas et limites

Chaque clé a un quota mensuel configurable (par défaut 10 000 req/mois, max 1 000 000). Les quotas se réinitialisent le 1er de chaque mois UTC.

• En-têtes X-Twin-Quota-{Limit,Used,Remaining} dans chaque réponse indiquent l'état actuel.
• L'endpoint /health ne consomme pas de quota : utilise-le pour vérifier la clé sans dépenser.
• Quota épuisé → 429 avec champ resetsAt en ISO UTC.

Codes d'erreur

Toutes les réponses d'erreur suivent la structure { error: { type, code, message, ... } }.

• 401 MISSING_API_KEY — aucun en-tête X-Twin-Key ni Authorization Bearer envoyé.
• 401 INVALID_API_KEY_FORMAT — la clé ne correspond pas au format atk_live_<8 hex>_<32 hex>.
• 401 INVALID_OR_REVOKED_API_KEY — la clé n'existe pas, a été révoquée ou a expiré.
• 403 FORBIDDEN MISSING_SCOPE — la clé manque du scope requis pour l'endpoint.
• 403 NO_TWIN_PURCHASED — le propriétaire n'a encore acheté aucun AfiniTwin.
• 425 TWIN_NOT_READY — l'AfiniTwin est en cours de génération (status pending ou generating). Réessaie dans 30s.
• 429 MONTHLY_QUOTA_EXCEEDED — quota mensuel épuisé. Réinitialisé le 1er du mois suivant UTC.

Exemples d'intégration

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

Sécurité

• Les clés sont des secrets. Ne les publie jamais dans des dépôts, frontends ou endpoints accessibles de l'extérieur.
• Une clé révoquée cesse de fonctionner à l'instant. Ton intégration doit réagir à 401 INVALID_OR_REVOKED_API_KEY en faisant tourner la clé.
• Si tu redescends du plan Professionnel, les clés restent stockées mais les endpoints renvoient 403 jusqu'à ce que tu remontes à Professionnel.
• Pour la confidentialité, nous n'acceptons pas les intégrations qui transfèrent le PCP d'un utilisateur à des systèmes qu'il n'a pas autorisés. La responsabilité incombe à celui qui utilise la clé.

Changelog

• v1.0 (2026-05-10): Lancement. 5 endpoints publics (health, me, historic, snapshots/:id, preset/:slug). Scope unique twin:read. Quota mensuel configurable par clé.

ton dashboard →