Documentação · SDKs

SDKs oficiais: TypeScript e Python

Dois SDKs finos, com zero dependências de runtime, mapeando um a um os endpoints reais da API v1. O que a API não tem, o SDK não finge ter.

Estado atual — leia antes de usar

Publicação no npm e no PyPI ainda está pendente (aguarda tokens de publicação — dívida técnica declarada). Por enquanto os pacotes vivem no monorepo e são consumidos via workspace. A autenticação usa o token interno da plataforma — uso server-side apenas; a API pública com API keys de cliente é a Fase 8 do roadmap. E não existe brands.create nos SDKs porque a rota não existe na API: marcas são cadastradas pelo app.

Exemplos

@genopt/sdk

import { GenOptClient } from '@genopt/sdk';

const genopt = new GenOptClient({
  apiKey: process.env.GENOPT_API_TOKEN!, // hoje: token interno (server-side)
  // baseUrl: 'https://api.genopt.ai'    // default
});

// Dispara um scan (202 — processamento assíncrono no worker)
const { scanId, jobId } = await genopt.scans.create({ brandId: 'brand_123' });

// Matriz de confabulação + evidências
const confabs = await genopt.confabulations.list('brand_123', {
  engine: 'CHATGPT',
  window: '30d',
});

// Evidência de um run, reverificação e bundle exportável
const evidence = await genopt.evidence.get('run_456');
await genopt.evidence.verifyAgain('run_456');
const bundleHtml = await genopt.evidence.bundle('run_456', 'html');

// Ground truth da marca
await genopt.groundTruth.list('brand_123');
await genopt.groundTruth.refresh('brand_123');

// Verificação pública de evidência — sem auth, qualquer pessoa pode chamar
await genopt.publicEvidence.get('<sha256>');
await genopt.publicEvidence.check('<sha256>', 'conteúdo em mãos');

genopt-sdk

from genopt_sdk import GenOptClient, GenOptAPIError

client = GenOptClient(api_key=os.environ["GENOPT_API_TOKEN"])

# Dispara um scan (202 — processamento assíncrono no worker)
scan = client.scans.create(brand_id="brand_123")

# Matriz de confabulação + evidências
confabs = client.confabulations.list(
    "brand_123", engine="CHATGPT", window="30d"
)

# Evidência de um run, reverificação e bundle exportável
evidence = client.evidence.get("run_456")
client.evidence.verify_again("run_456")
bundle_html = client.evidence.bundle("run_456", format="html")

# Ground truth da marca
client.ground_truth.list("brand_123")
client.ground_truth.refresh("brand_123")

# Verificação pública de evidência — sem auth
client.public_evidence.get(sha256)
client.public_evidence.check(sha256, conteudo)

# Erros: respostas não-2xx levantam GenOptAPIError
try:
    client.evidence.get("nao-existe")
except GenOptAPIError as err:
    print(err.status, err.body)  # 404 {'error': 'run não encontrado'}

O que os SDKs cobrem

Cada método mapeia uma rota real: scans.create, confabulations.list, evidence.get / verifyAgain / bundle, groundTruth.list / refresh e as duas rotas públicas em publicEvidence (no Python, os mesmos nomes em snake_case). A tabela completa método → endpoint, com códigos de erro, está em /docs/api. Respostas não-2xx viram exceção (GenOptApiError / GenOptAPIError) carregando status e o corpo que a API devolveu.