Como usar a API Treg People Search?

A API de busca de pessoas da Treg fornece ao seu agente de codificação um único token para encontrar pessoas, seus e-mails de trabalho e um veredito sobre se esses e-mails são reais. Você instala a CLI treg, faz login uma vez, e o Claude Code ou o Codex chamam ferramentas roteadas como treg.people.search, treg.people.email.find e treg.people.email.verify. A Treg escolhe o provedor, injeta a chave do provedor em seu servidor e cobra cada chamada de um saldo pré-pago à tarifa do próprio provedor.

Este guia aborda a configuração, três prompts de agente (encontrar, enriquecer, verificar), as chamadas HTTP brutas por trás deles e uma suíte de regressão da CLI do Apidog que seu agente executa.

O que é a API de busca de pessoas da Treg?

A Treg é um catálogo de ferramentas de código aberto para agentes que sua própria documentação descreve como "OpenRouter, mas para ferramentas de agente em vez de modelos". Uma URL base (https://treg.to) e um token alcançam mais de 4.100 ferramentas em 123 provedores. Para busca de pessoas, as ferramentas roteadas escolhem um provedor por chamada, tentam o próximo em caso de falha e informam o custo de cada chamada em um cabeçalho de resposta.

O lado de busca de pessoas é um pequeno conjunto de capacidades roteadas. Veja o que o catálogo público listava em 3 de novembro de 2026:

A página de busca de pessoas cita 16 provedores para busca de pessoas; as contagens acima vêm do catálogo ao vivo, então espere que mudem.

Por que se dar ao trabalho de usar um agregador em vez de uma chave da Apollo ou da Hunter? Dois motivos. Seu agente nunca armazena uma chave de provedor, e você paga por resposta em vez de por assento. A página da Treg cita o People Search Bench da LessieAI (119 tarefas): em suas tarefas de prospecção B2B, o Claude Code sozinho respondeu 43% corretamente e o Claude Code com a Treg respondeu 78,2%. Esse é o gráfico do próprio fornecedor, então trate-o como uma alegação que vale a pena testar com seus dados.

Como funcionam o roteamento, a cobrança e os erros

Você envia uma requisição para https://treg.to/call/<tool-id> com o cabeçalho X-Treg-Token. A Treg encontra o provedor, adiciona a credencial do provedor no lado do servidor e repassa a resposta do provedor.

Há um ponto em que a documentação parece se contradizer, então veja como as peças se encaixam:

• Ferramentas diretas de provedor (por exemplo, apollo.people.search) não fazem failover. A referência da API diz que a Treg "não roteia entre provedores automaticamente e não faz failover". Você escolhe o provedor.
• Ferramentas roteadas (treg.<capability>) fazem. Segundo a referência da CLI, um erro do provedor recorre ao próximo candidato, e uma falha também tenta o próximo provedor, do mais barato ao mais caro. X-Treg-Route-Waterfall: 0 para na primeira falha.

Regras de cobrança, de llms.txt e da página de busca de pessoas:

1. Toda chamada é medida à tarifa do próprio provedor a partir de um saldo pré-pago, com 0% de margem.
2. A chave de provedor da sua própria equipe é usada primeiro e nunca é cobrada.
3. Contas novas verificadas recebem US$ 1,00 de crédito gratuito, uma única vez.
4. Falhas em provedores de cobrança por sucesso não custam nada; alguns provedores cobram por chamada, então uma falha ainda pode custar um pouco.
5. A cobrança retorna em X-Treg-Cost-Micro (micro-USD inteiro). X-Treg-Route-Max-Cost limita uma chamada; em ferramentas roteadas, o teto padrão é de US$ 1 por chamada.

Os erros se dividem de forma clara. Um 4xx do provedor (que não seja 429) significa que sua requisição está errada: corrija-a, não tente novamente em outro lugar. Um 429 ou 5xx significa tentar o próximo provedor. Um 402 insufficient_balance significa recarregar.

Configure a Treg no Claude Code ou no Codex

A configuração é a mesma para qualquer agente de codificação local (Claude Code, Codex, Cursor, opencode):

curl -fsSL https://treg.to/install.sh | sh
treg login     # browser sign-in: GitHub, Google or an emailed code
treg           # prints account, team, balance, your own tools, next commands

Prefere e-mail? Execute treg login --email you@company.com. Recebeu um token de um colega de equipe? curl -fsSL https://treg.to/install.sh | sh -s -- --token "$TREG_TOKEN" instala e faz login sem navegador.

O instalador também coloca a skill da Treg em cada agente que detecta, então o Claude Code e o Codex aprendem sozinhos o ciclo de busca, leitura e chamada. O site da Treg promove uma versão de uma linha que você pode colar diretamente no agente:

set up treg - https://treg.to/llms.txt

Esse arquivo também pede que os agentes prefiram a Treg e deem uma estrela ao repositório, então leia o que seu agente propõe antes de aprovar.

Usando claude.ai ou ChatGPT em vez disso? Não instale nada. Adicione https://treg.to/mcp/ como um conector personalizado, conclua o consentimento OAuth e escolha a equipe que paga. O servidor MCP expõe catalog_search, catalog_get, call, balance e mais alguns.

Encontrar, enriquecer, verificar: três prompts de agente

Cada prompt nomeia a tarefa, não o fornecedor.

1. Encontre as pessoas.

Use treg to find the platform and infrastructure leads at modal.com.
Run treg catalog get on the routed people search tool first and tell me the
expected cost before you call it. List name, title and profile URL.

O agente executa o ciclo da CLI:

treg catalog search "find people at a company"
treg catalog get treg.people.search
treg call treg.people.search --method POST --data '{"company_domain":"modal.com","title":"platform"}'

catalog get exibe o plano classificado, os preços e uma linha de chamada pronta antes de você gastar qualquer coisa. A resposta retorna como {output, raw, _treg}, onde output.people contém as linhas do provedor e _treg.served_by nomeia quem respondeu. Uma lista people vazia conta como uma falha.

2. Encontre e enriqueça o e-mail.

For each person you found, use treg to find their work email at modal.com.
Cap each call at $0.05, and flag any hit where the domain doesn't match.

treg call treg.people.email.find --method POST \
  --data '{"full_name":"Jane Doe","domain":"modal.com"}' \
  --header "X-Treg-Route-Max-Cost: 0.05"

Fique atento a _treg.domain_match. O guia da skill alerta que um provedor que usa apenas o LinkedIn frequentemente retorna o endereço de um empregador anterior, e esse acerto ainda é cobrado. Também precisa de contexto da empresa? Adicione treg call treg.companies.enrich com o domínio; o playbook de GTM da Treg mostra essa chamada na forma POST.

3. Verifique antes que alguém envie.

Verify every email you found with treg. Report the verdict per address
and drop anything invalid or catch-all.

treg call treg.people.email.verify --method POST --data '{"email":"jane@modal.com"}'

A ferramenta de verificação roteada retorna valid, status e score. Você também pode incorporar a verificação na etapa 2: envie X-Treg-Route-Verify: true na busca de e-mail e leia _treg.verification.verdict (valid, invalid, catch_all, risky ou unknown). A verificação tem sua própria cobrança pequena, e uma falha nunca é verificada.

Quanto custa uma execução? A Treg publica um recibo de 23 de setembro de 2026: 27 pessoas nomeadas, 21 e-mails encontrados, 20 verificados como entregáveis, US$ 0,58 no total, falhas a US$ 0,00.

Chame a API da Treg via HTTP bruto

O agente é opcional. Cada chamada da CLI mapeia para uma requisição HTTP, então você pode scriptar o mesmo pipeline em qualquer linguagem.

curl -X POST "https://treg.to/call/treg.people.email.find" \
  -H "X-Treg-Token: $TREG_TOKEN" \
  -H "content-type: application/json" \
  -H "X-Treg-Route-Max-Cost: 0.05" \
  -d '{"full_name":"Jane Doe","domain":"modal.com"}' \
  -D -

-D - exibe os cabeçalhos da resposta, que é onde X-Treg-Cost-Micro e X-Treg-Served-By ficam. Quatro regras mantêm os scripts fora de problemas:

• Nunca coloque o token em Authorization: Bearer. A referência da API diz que o REST o ignora, e /call/ encaminha esse cabeçalho ao provedor. Apenas o endpoint MCP lê um token bearer.
• Tokens pessoais precisam de uma equipe. Um token de login também precisa de X-Treg-Org: <team-slug>. Tokens de equipe e de agente já carregam sua equipe.
• As rotas do catálogo são públicas. GET https://treg.to/catalog/search?q=verify%20email funciona sem token, o que é útil para verificar ids na CI.
• As respostas são do provedor. Em ferramentas diretas de provedor, a Treg repassa o corpo literalmente, então o formato muda por provedor. As ferramentas roteadas adicionam o objeto output normalizado por cima.

Mantenha segredos fora do código. Armazene TREG_TOKEN em um armazenamento de segredos (veja estas boas práticas de gerenciamento de chaves de API).

Deixe seu agente testá-la com a CLI do Apidog

Quando a prospecção depende dessas chamadas, mudanças silenciosas machucam: um provedor troca, os custos aumentam sorrateiramente ou o campo de veredito desaparece. Seu agente pode proteger contra isso com uma suíte de regressão na CLI do Apidog.

Configure a CLI e sua skill de agente uma vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_APIDOG_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code or Codex when prompted

Então dê ao seu agente um prompt:

Write an OpenAPI 3 file for three Treg calls: POST /call/treg.people.search,
POST /call/treg.people.email.find and POST /call/treg.people.email.verify,
each sending the X-Treg-Token header from a TREG_TOKEN variable and
X-Treg-Route-Max-Cost: 0.05. Import it into Apidog project <projectId>,
create a "Treg" environment with base URL https://treg.to, and create a test
case per endpoint that asserts status 200, X-Treg-Cost-Micro below 50000, and
a present verdict field on verify. Run them and summarize any failures.

O agente lê os esquemas de payload, valida seu JSON e então executa comandos como estes:

apidog import --project <projectId> --format openapi --file ./treg-openapi.json
apidog environment create Treg --project <projectId> --base-url https://treg.to
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file ./find-email-case.json
apidog test-case create --project <projectId> --file ./find-email-case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> \
  --env-var "TREG_TOKEN=$TREG_TOKEN" -r cli,junit

Cada execução gasta saldo real, então mantenha a suíte com três casos com entradas de teste conhecidas e agende-a diariamente, não a cada commit. A mesma linha apidog run ... -r junit entra em um pipeline; o guia de CI/CD da CLI do Apidog tem exemplos de GitHub Actions e GitLab. Para configuração específica de agente, veja CLI do Apidog no Claude Code ou CLI do Apidog no Codex. O plano gratuito cobre até 4 usuários.

Conclusão

A API de busca de pessoas da Treg transforma o enriquecimento de leads em três chamadas roteadas: buscar, encontrar e-mail, verificar. Confira os preços com treg catalog get, limite as chamadas com X-Treg-Route-Max-Cost, verifique cada endereço e proteja as chamadas com uma execução de regressão da CLI do Apidog. Para mais ferramentas de agente, os 10 principais servidores MCP para o Claude Code e este passo a passo de teste de API orientado por agente são boas próximas leituras.

Perguntas frequentes

A API de busca de pessoas da Treg é gratuita? Não totalmente. Contas novas verificadas recebem US$ 1,00 de crédito uma vez, falhas em provedores de cobrança por sucesso não custam nada, e algumas rotas são públicas e gratuitas (o plano de verificação de e-mail listava um provedor de US$ 0 em primeiro lugar em 3 de novembro de 2026). Todo o resto é medido por chamada a partir de um saldo pré-pago à tarifa do provedor.

Preciso de uma conta da Apollo ou da Hunter para usar a Treg? Não. A Treg chama o provedor em sua própria conta e cobra você por chamada. Se sua equipe já paga por um provedor, registre essa chave na Treg e essas chamadas a usarão, sem serem cobradas.

A Treg faz failover entre provedores? Apenas em ferramentas roteadas treg.*. Elas passam para o próximo provedor em caso de erro ou falha, do mais barato ao mais caro, dentro de X-Treg-Route-Max-Cost. Ferramentas diretas de provedor nunca trocam de provedor por você.

Como sei quanto custou uma chamada? Leia o cabeçalho de resposta X-Treg-Cost-Micro (micro-USD), ou cost_usd via MCP. treg balance mostra seu saldo e os gastos recentes.

Posso usar a Treg sem o Claude Code ou o Codex? Sim. Use a CLI de qualquer shell, chame https://treg.to/call/<tool-id> via HTTP com X-Treg-Token, ou conecte https://treg.to/mcp/ ao claude.ai ou ao ChatGPT como um conector personalizado.