AfiniTwin B2B API

Authenticated REST API to programmatically access a user's AfiniTwin Portable and serve it as system prompt in CRMs, custom assistants, or AI pipelines. Built for B2B integrators.

Authentication

Every call requires the X-Twin-Key header (or Authorization: Bearer atk_live_...). The plaintext is delivered only once when the key is created; the DB stores only its SHA-256 hash. If you lose the plaintext, revoke the key and create another.

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

Endpoints

Health check (no quota cost)

Returns {ok: true, apiKeyId, userId, scopes, serverTime}. Useful to verify the key is alive without spending quota.

GET /v1/public/twin/health

Identity and quota

Returns the owner's plan, the key's scopes, used/remaining monthly quota, and the most recent ready-state AfiniTwin.

GET /v1/public/twin/me

Snapshot listing

All the owner's AfiniTwins with date, version, source, and status. Useful for integrators who want to list options to the user.

GET /v1/public/twin/historic

Snapshot metadata

Information about a snapshot (does NOT include the full PCP — that goes via /preset/:slug). Useful to display metadata or decide whether to reuse an old one.

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

Download artifact

Returns the chosen preset artifact in the requested format, ready to inject as system prompt. Accepts the same query params as the web version. Every call counts toward the monthly quota.

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 and limits

Each key has a configurable monthly quota (default 10,000 req/month, max 1,000,000). Quotas reset on the 1st of each UTC month.

• X-Twin-Quota-{Limit,Used,Remaining} headers in every response indicate the current state.
• The /health endpoint does not consume quota: use it to verify the key without spending.
• Quota exhausted → 429 with resetsAt field in ISO UTC.

Error codes

All error responses follow the { error: { type, code, message, ... } } structure.

• 401 MISSING_API_KEY — no X-Twin-Key header or Authorization Bearer was sent.
• 401 INVALID_API_KEY_FORMAT — the key does not match the atk_live_<8 hex>_<32 hex> format.
• 401 INVALID_OR_REVOKED_API_KEY — the key does not exist, has been revoked, or has expired.
• 403 FORBIDDEN MISSING_SCOPE — the key lacks the scope required for the endpoint.
• 403 NO_TWIN_PURCHASED — the owner has not purchased any AfiniTwin yet.
• 425 TWIN_NOT_READY — the AfiniTwin is being generated (status pending or generating). Retry in 30s.
• 429 MONTHLY_QUOTA_EXCEEDED — monthly quota exhausted. Resets on the 1st of next UTC month.

Integration examples

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

Security

• Keys are secrets. Never publish them in repositories, frontends, or externally accessible endpoints.
• A revoked key stops working instantly. Your integration must react to 401 INVALID_OR_REVOKED_API_KEY by rotating the key.
• If you downgrade from Professional, the keys remain stored but the endpoints return 403 until you upgrade back to Professional.
• For privacy, we do not accept integrations that forward a user's PCP to systems they have not authorized. Responsibility lies on whoever uses the key.

Changelog

• v1.0 (2026-05-10): Launch. 5 public endpoints (health, me, historic, snapshots/:id, preset/:slug). Single scope twin:read. Per-key configurable monthly quota.

your dashboard →