Deixe um agente provisionar todo o pipeline

Um agente não faz nada aqui até você entregar uma chave a ele. Criar a conta, verificar o e-mail do dono e gerar essa chave são etapas de navegador, e mantê-las assim é justamente o objetivo: quem é dono da relação de cobrança decide o que o agente pode alcançar, e o agente tem uma única credencial que você vê em uma lista e revoga com um clique.

Isso também significa que não há malabarismo com tokens. O agente nunca toca em um endpoint de conta, nunca mantém uma sessão e não consegue ampliar o próprio acesso. Tudo o que ele faz roda em /v1/* com a chave que você deu.

No painel, em Organização → Chaves de API, Nova chave pede um nome, uma expiração opcional e Acesso a projetos. Deixe em Todos os projetos e a chave alcança tudo na organização. Escolha um projeto e a chave fica vinculada a ele, que é como você mantém uma execução sem supervisão dentro de um raio de impacto que você escolheu. O valor aparece uma única vez, então copie-o direto para o ambiente do agente.

O painel cria e revoga chaves, mas não altera o escopo delas, então ampliar ou restringir um vínculo depois significa gerar uma substituta e aposentar a antiga. Permissões de ação por chave estão planejadas. Até lá, uma chave tem permissões de nível membro: lê tudo dentro do escopo e cria, atualiza, ativa e desativa, tenta de novo e reenvia livremente, enquanto exclusões, revelação e rotação do segredo de assinatura, rotação de máscara, provisionamento de conectores e mudanças de cobrança ficam com um admin ou dono no painel.

Três chamadas: uma origem para receber, um destino para onde enviar e uma conexão ligando os dois. A resposta da origem traz a ingestUrl, que é a única coisa de que o seu provedor precisa.

# Source. The ingestUrl is what your provider gets.curl -s "$API/v1/sources" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe", "provider": "stripe", "verifierConfig": { "secret": "whsec_..." } }'→ { "id": "src_...", "ingestUrl": "https://sdhk.events/<maskId>", ... } # Destination, then a connection joining the two.curl -s "$API/v1/destinations" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Billing", "type": "http", "url": "https://acme.example/hooks" }' curl -s "$API/v1/connections" -H "authorization: Bearer $SDHK_KEY" \  -H 'content-type: application/json' \  -d '{ "name": "Stripe → Billing", "sourceId": "src_...", "destinationId": "dest_..." }'

Informar um provedor conhecido traz o esquema de assinatura dele junto, então o agente fornece um segredo em vez de pesquisar um formato de assinatura. As origens também aceitam e-mail de entrada, assunto do guia de e-mail.

Um agente que só consegue escrever está adivinhando. A mesma API retorna cada evento com o resultado da verificação e cada entrega com suas tentativas, e é isso que torna possível depurar uma execução sem supervisão.

Uma falha de assinatura retorna um 401 deliberadamente vago para quem chamou, porque explicar qual verificação falhou para um remetente não autenticado transformaria a resposta em um oráculo. O motivo fica registrado no evento, onde um agente autenticado pode lê-lo.

# Why did nothing arrive?curl -s "$API/v1/events?status=rejected" -H "authorization: Bearer $SDHK_KEY"→ rejectionReason: "signature_mismatch" | "timestamp_out_of_tolerance" | ... # Re-send one failed delivery. Free, creates nothing new.curl -s -X POST "$API/v1/deliveries/dlv_.../retry" -H "authorization: Bearer $SDHK_KEY" # Run an event through its connections again. Billable.curl -s -X POST "$API/v1/events/evt_.../replay" -H "authorization: Bearer $SDHK_KEY"

• /v1/spec.json é o esquema OpenAPI 3 de todos os endpoints, e /v1 é a referência interativa sobre a mesma especificação.
• /llms.txt orienta um modelo rapidamente. /llms-full.txt é o passo a passo completo, incluindo a semântica de erros e os limites que pegam de surpresa.
• Os erros são tipados, não em prosa. QUOTA_EXCEEDED e RATE_LIMITED são códigos distintos para ramificar diretamente. Erros de limite do plano, como o teto de conectores, ficam em FORBIDDEN, com um payload data (limit, current) trazendo os detalhes.

• Dê a cada agente sua própria chave. Assim, revogar uma não custa mais nada, e a coluna de último uso mostra qual agente ficou em silêncio.
• Vincule a chave a um projeto, a menos que o agente realmente gerencie projetos. É o único escopo disponível hoje, e ele não pode ser alterado depois que a chave é gerada.
• Ramifique pelo código de erro, nunca pelo texto da mensagem. As mensagens são escritas para humanos, e o 401 da ingestão é intencionalmente pouco informativo.
• Consulte ?status=rejected antes de reenviar qualquer coisa. Uma assinatura que nunca foi verificada também não vai ser verificada na segunda tentativa.
• Prefira tentar a entrega de novo a reenviar o evento quando um consumidor falhou. A nova tentativa é grátis, e o reenvio é cobrado.