API B2B AfiniTwin

API REST autenticada para acessar programaticamente o AfiniTwin Portable de um usuário e servir como system prompt em CRMs, assistentes próprios ou pipelines de IA. Pensada para integradores B2B.

Gerar keys: apenas plano Profissional. Qualquer um pode ler esta documentação. Para criar e revogar API keys é preciso ter plano Profissional ativo (ou voucher equivalente). Gerencia-as a partir do seu dashboard.

Autenticação

Toda chamada requer o header X-Twin-Key (ou Authorization: Bearer atk_live_...). O plaintext é entregue uma única vez ao criar a key; no DB se guarda apenas seu hash SHA-256. Se você perder o plaintext, revoga a key e cria outra.

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

Endpoints

Health check (não consome quota)

Devolve {ok: true, apiKeyId, userId, scopes, serverTime}. Útil para validar que a key segue viva sem gastar quota.

GET /v1/public/twin/health

Identidade e quota

Devolve o plano do proprietário, os scopes da key, a quota mensal usada/restante e o AfiniTwin mais recente em estado ready.

GET /v1/public/twin/me

Listagem de snapshots

Todos os AfiniTwins do proprietário com data, versão, fonte e estado. Útil para integradores que querem listar opções ao usuário.

GET /v1/public/twin/historic

Metadados de um snapshot

Informações sobre um snapshot (NÃO inclui o PCP completo — isso passa por /preset/:slug). Útil para mostrar metadados ou decidir se reutilizar um antigo.

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

Baixar artefato

Devolve o artefato do preset escolhido no formato indicado, pronto para injetar como system prompt. Aceita os mesmos query params da versão web. Cada chamada conta para a quota mensal.

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 e limites

Cada key tem quota mensal configurável (default 10.000 req/mês, máximo 1.000.000). As quotas resetam no dia 1 de cada mês UTC.

Headers X-Twin-Quota-{Limit,Used,Remaining} em cada resposta indicam o estado atual.
O endpoint /health não consome quota: usa para verificar a key sem gastar.
Quota esgotada → 429 com campo resetsAt em ISO UTC.

Códigos de erro

Todas as respostas de erro seguem a estrutura { error: { type, code, message, ... } }.

401 MISSING_API_KEY — nenhum header X-Twin-Key nem Authorization Bearer enviado.
401 INVALID_API_KEY_FORMAT — a key não corresponde ao formato atk_live_<8 hex>_<32 hex>.
401 INVALID_OR_REVOKED_API_KEY — a key não existe, foi revogada ou expirou.
403 FORBIDDEN MISSING_SCOPE — a key não tem o scope necessário para o endpoint.
403 NO_TWIN_PURCHASED — o proprietário ainda não comprou nenhum AfiniTwin.
425 TWIN_NOT_READY — o AfiniTwin está sendo gerado (status pending ou generating). Tenta novamente em 30s.
429 MONTHLY_QUOTA_EXCEEDED — quota mensal esgotada. Reset no dia 1 do mês seguinte UTC.

Exemplos de integração

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

Segurança

As keys são segredos. Nunca as publiques em repositórios, frontends ou endpoints acessíveis de fora.
Uma key revogada deixa de funcionar na hora. Sua integração deve reagir a 401 INVALID_OR_REVOKED_API_KEY rotacionando a key.
Se você descer do plano Profissional, as keys ficam salvas mas os endpoints devolvem 403 até voltar a Profissional.
Por privacidade, não aceitamos integrações que reenviem o PCP de um usuário a sistemas que ele não autorizou. A responsabilidade recai sobre quem usa a key.

Changelog

v1.0 (2026-05-10): Lançamento. 5 endpoints públicos (health, me, historic, snapshots/:id, preset/:slug). Scope único twin:read. Quota mensal configurável por key.

seu dashboard →