AfiniTwin B2B-API

Authentifizierte REST API, um programmatisch auf den AfiniTwin Portable eines Nutzers zuzugreifen und ihn als System Prompt in CRMs, eigenen Assistenten oder KI-Pipelines auszuliefern. Für B2B-Integratoren konzipiert.

Authentifizierung

Jeder Call erfordert den Header X-Twin-Key (oder Authorization: Bearer atk_live_...). Das Plaintext wird beim Erstellen der Key nur einmal geliefert; in der DB wird nur sein SHA-256-Hash gespeichert. Wenn du das Plaintext verlierst, widerrufe die Key und erstelle eine neue.

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

Endpunkte

Health Check (verbraucht keine Quote)

Gibt {ok: true, apiKeyId, userId, scopes, serverTime} zurück. Nützlich, um zu prüfen, ob die Key lebt, ohne Quote zu verbrauchen.

GET /v1/public/twin/health

Identität und Quote

Gibt den Plan des Besitzers, die Scopes der Key, die monatliche verbrauchte/verbleibende Quote und den jüngsten AfiniTwin im Status ready zurück.

GET /v1/public/twin/me

Snapshot-Liste

Alle AfiniTwins des Besitzers mit Datum, Version, Quelle und Status. Nützlich für Integratoren, die dem Nutzer Optionen anzeigen wollen.

GET /v1/public/twin/historic

Snapshot-Metadaten

Informationen über einen Snapshot (enthält NICHT das vollständige PCP — das geht über /preset/:slug). Nützlich, um Metadaten anzuzeigen oder zu entscheiden, ob ein älterer wiederverwendet werden soll.

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

Artefakt herunterladen

Gibt das Artefakt des gewählten Presets im angeforderten Format zurück, bereit als System Prompt zu injizieren. Akzeptiert dieselben Query Params wie die Web-Version. Jeder Call zählt für die monatliche Quote.

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

Quoten und Limits

Jede Key hat eine konfigurierbare monatliche Quote (Standard 10.000 Req/Monat, max 1.000.000). Die Quoten werden am 1. jedes UTC-Monats zurückgesetzt.

• X-Twin-Quota-{Limit,Used,Remaining}-Header in jeder Antwort zeigen den aktuellen Stand.
• Der /health-Endpunkt verbraucht keine Quote: nutze ihn, um die Key ohne Verbrauch zu verifizieren.
• Quote erschöpft → 429 mit Feld resetsAt in ISO UTC.

Fehlercodes

Alle Fehlerantworten folgen der Struktur { error: { type, code, message, ... } }.

• 401 MISSING_API_KEY — kein X-Twin-Key-Header oder Authorization Bearer gesendet.
• 401 INVALID_API_KEY_FORMAT — die Key entspricht nicht dem Format atk_live_<8 hex>_<32 hex>.
• 401 INVALID_OR_REVOKED_API_KEY — die Key existiert nicht, wurde widerrufen oder ist abgelaufen.
• 403 FORBIDDEN MISSING_SCOPE — der Key fehlt der für den Endpunkt erforderliche Scope.
• 403 NO_TWIN_PURCHASED — der Besitzer hat noch keinen AfiniTwin gekauft.
• 425 TWIN_NOT_READY — der AfiniTwin wird generiert (Status pending oder generating). In 30s erneut versuchen.
• 429 MONTHLY_QUOTA_EXCEEDED — monatliche Quote erschöpft. Reset am 1. des nächsten UTC-Monats.

Integrationsbeispiele

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

Sicherheit

• Keys sind Geheimnisse. Veröffentliche sie nie in Repositories, Frontends oder extern zugänglichen Endpunkten.
• Eine widerrufene Key funktioniert sofort nicht mehr. Deine Integration muss auf 401 INVALID_OR_REVOKED_API_KEY reagieren, indem sie die Key rotiert.
• Wenn du vom Professional-Plan herunterstufst, bleiben die Keys gespeichert, aber die Endpunkte geben 403 zurück, bis du wieder auf Professional gehst.
• Aus Datenschutzgründen akzeptieren wir keine Integrationen, die das PCP eines Nutzers an Systeme weiterleiten, die er nicht autorisiert hat. Die Verantwortung liegt beim Nutzer der Key.

Changelog

• v1.0 (2026-05-10): Launch. 5 öffentliche Endpunkte (health, me, historic, snapshots/:id, preset/:slug). Einziger Scope twin:read. Pro Key konfigurierbare monatliche Quote.

deinem Dashboard →