API B2B AfiniTwin

API REST autenticada para acceder programáticamente al AfiniTwin Portable de un usuario y servirlo como system prompt en CRMs, asistentes propios o pipelines de IA. Pensada para integradores B2B.

Autenticación

Todas las llamadas requieren cabecera X-Twin-Key (o Authorization: Bearer atk_live_...). El plaintext se entrega una sola vez al crear la key; en BD solo se guarda el hash SHA-256. Si pierdes el plaintext, revoca la key y crea otra.

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

Endpoints

Health check (no consume cuota)

Devuelve {ok: true, apiKeyId, userId, scopes, serverTime}. Útil para validar que la key sigue viva sin gastar quota.

GET /v1/public/twin/health

Identidad y cuota

Devuelve plan del propietario, scopes de la key, cuota mensual usada/restante, y el AfiniTwin más reciente en estado ready.

GET /v1/public/twin/me

Listado de snapshots

Todos los AfiniTwin del propietario con fecha, versión, fuente y estado. Útil para integradores que quieren listar opciones al usuario.

GET /v1/public/twin/historic

Metadatos de un snapshot

Información del snapshot (NO incluye PCP completo — eso va por /preset/:slug). Útil para enseñar metadata o decidir si reusar uno antiguo.

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

Descargar artefacto

Devuelve el artefacto del preset elegido en el formato indicado, listo para inyectar como system prompt. Acepta los mismos query params que la versión web. Cada llamada cuenta para la cuota mensual.

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

Cuotas y límites

Cada key tiene cuota mensual configurable (default 10.000 req/mes, máximo 1.000.000). Las cuotas se reinician el día 1 de cada mes UTC.

• Cabeceras X-Twin-Quota-{Limit,Used,Remaining} en cada respuesta indican el estado actual.
• El endpoint /health no consume cuota: úsalo para verificar la key sin gastar.
• Cuota agotada → 429 con campo resetsAt en ISO UTC.

Códigos de error

Todas las respuestas de error siguen la estructura { error: { type, code, message, ... } }.

• 401 MISSING_API_KEY — no se envió header X-Twin-Key ni Authorization Bearer.
• 401 INVALID_API_KEY_FORMAT — la key no tiene el formato atk_live_<8 hex>_<32 hex>.
• 401 INVALID_OR_REVOKED_API_KEY — la key no existe, ha sido revocada o expiró.
• 403 FORBIDDEN MISSING_SCOPE — la key no tiene el scope necesario para el endpoint.
• 403 NO_TWIN_PURCHASED — el propietario no ha comprado ningún AfiniTwin todavía.
• 425 TWIN_NOT_READY — el AfiniTwin está generándose (status pending o generating). Reintentar en 30s.
• 429 MONTHLY_QUOTA_EXCEEDED — cuota mensual agotada. Reset el día 1 del mes siguiente UTC.

Ejemplos de integración

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

Seguridad

• Las keys son secretos. Nunca las publiques en repositorios, frontends ni endpoints accesibles externamente.
• Una key revocada deja de funcionar al instante. Tu integración debe reaccionar a 401 INVALID_OR_REVOKED_API_KEY rotando la key.
• Si bajas de plan Profesional, las keys siguen guardadas pero los endpoints devuelven 403 hasta que vuelvas a Profesional.
• Por privacidad, no aceptamos integraciones que reenvíen el PCP de un usuario a sistemas no autorizados por él. La responsabilidad recae sobre quien usa la key.

Changelog

• v1.0 (2026-05-10): Lanzamiento. 5 endpoints públicos (health, me, historic, snapshots/:id, preset/:slug). Scope twin:read único. Quota mensual configurable por key.

tu dashboard →