Respawn Tech Dev

Autenticação

Como autenticar nas ferramentas com token de API, escopos e requisitos de conta.

Token de API

Todas as rotas em /v1/tools/* exigem um token de API, criado no dashboard em APIs.

FormaExemplo
Header dedicado (recomendado)X-API-Token: rsk_live_...
AuthorizationAuthorization: ApiKey rsk_live_...
Authorization (alternativo)Authorization: Token rsk_live_...

Boas práticas

Guarde o token na variável de ambiente RESPAWN_API_TOKEN, crie um token por integração com os escopos mínimos necessários e revogue os que não usar mais.

Requisitos da conta

Antes de qualquer chamada às ferramentas, a conta precisa ter:

  • E-mail verificado — caso contrário, auth.email_not_verified (403).
  • Saldo não negativo — conta suspensa retorna billing.user_bankrupt (402).
  • Créditos suficientes — operações pagas sem saldo retornam billing.insufficient_credits (402).

Escopos

Cada rota aceita um conjunto de escopos; basta o token ter um deles. Se faltar permissão, a API retorna scope.missing (403) com details.required e details.provided. Os escopos aceitos por cada endpoint aparecem no card do endpoint.

EscopoPermite
tools:manageAcesso total a todas as ferramentas (inclui leitura e escrita).
tools:readLeitura genérica de QR Dinâmico, Verificação de URL, Base de conhecimento, Webhook Relay, Extrator de erro de CI e Página web para Markdown. Não cobre PDF.
tools:qr:dynamic:readListar, consultar e ver analytics de QR Dinâmico.
tools:qr:dynamic:manageCriar, editar, ativar/desativar e excluir QR Dinâmico (também permite leitura).
tools:qr:domains:manageCadastrar, editar, verificar e remover os domínios próprios do QR Dinâmico (domínios ativos são cobrados).
tools:pdf:readListar, consultar status e baixar conversões de PDF.
tools:pdf:manageConverter, criar batch e reprocessar falhas de PDF.
tools:safety:readConsultar a Verificação de URL e o proxy de favicon.
tools:ci:readExtrair as linhas de erro de um log de CI.
tools:web:readConverter páginas web em Markdown (para gravar o resultado numa base, exige também `tools:rag:manage`).
tools:rag:readLer bases de conhecimento: listar bases, documentos, seções e feedback.
tools:rag:queryBuscar nas bases de conhecimento: fazer buscas, rerank e registrar feedback de relevância.
tools:rag:manageGerenciar bases de conhecimento: criar, alterar e excluir bases e documentos (também permite ler e buscar).
tools:webhooks:readLer a configuração do Webhook Relay (projetos, endpoints, tipos de evento, fontes, rotas e canvas), o uso do mês e o log de mensagens.
tools:webhooks:sendEnviar mensagens pelo Webhook Relay (envio único e em lote). Não permite ler nem alterar a configuração.
tools:webhooks:manageGerenciar o Webhook Relay: projetos, endpoints, secrets, tipos de evento, fontes, rotas, layout do canvas, eventos de teste, reenvios e recuperação (também permite ler e enviar).
tools:realtime:publishPublicar mensagens em canais do Realtime pela API.
tools:realtime:subscribeLer o histórico e a presença dos canais do Realtime.
tools:realtime:manageGerenciar o Realtime: emitir tokens, consultar canais e estatísticas, configurar o webhook de canais, publicar e ler o histórico e a presença.
tools:notify:sendEnviar notificações pelo canal padrão ou por um canal escolhido.
tools:notify:manageGerenciar os canais de notificação (criar, alterar, testar e excluir) e ler o histórico de envios.
tools:learnings:readRecuperar aprendizados salvos na Memória de aprendizados.
tools:learnings:writeSalvar e esquecer aprendizados na Memória de aprendizados.
tools:video:renderRenderizar vídeos (cobrado por segundo renderizado) e validar o roteiro (`validate_video`, `preview_video_frame`).
tools:video:readListar renders de vídeo, consultar o status e obter o link do MP4.
tools:audio:transcribeTranscrever áudio (cobrado por minuto), resumir e traduzir transcrições.
tools:audio:readListar os jobs de áudio, consultar o status e obter o link do resultado, além do catálogo de vozes.
tools:audio:speakGerar fala a partir de texto (por 1.000 caracteres), sons e músicas (por segundo) e falar uma gravação de novo com outra voz; no MCP, também criar e apagar vozes clonadas.
tools:audio:processAnalisar e converter áudio (cobrado por chamada e por minuto).
mcp:useUso por agentes de IA: permite usar a chave no servidor MCP.
account:readLer saldo e limites: consultar o saldo de créditos e o limite diário de gasto.

PDF é mais restritivo na leitura

Rotas de leitura de PDF aceitam apenas tools:pdf:read ou tools:manage. O escopo genérico tools:read e o tools:pdf:manage não dão acesso à leitura de PDF.

Combinações recomendadas

Caso de usoEscopos sugeridos
Gerar e gerenciar QR codestools:qr:dynamic:manage
Painel somente leitura de QRstools:qr:dynamic:read
Pipeline de PDFtools:pdf:manage + tools:pdf:read
Verificar URLs antes de exibirtools:safety:read
Assistente que busca na base de conhecimentotools:rag:query
Enviar e manter documentos da basetools:rag:manage
Agente de IA (MCP)mcp:use + os escopos das ferramentas que ele vai usar + account:read
Integração completatools:manage (mais simples, menos seguro)

Controles da chave

Além dos escopos, cada token pode ter controles configurados no dashboard. Eles valem em qualquer canal, na API e no MCP:

  • Expiração: depois da data, o token para de funcionar (auth.unauthorized).
  • Limite diário de gasto: uma cobrança que passaria do limite do dia é recusada com billing.spend_limit_reached (402), com details.limit, details.spent_today e details.required. O contador zera à meia-noite UTC.
  • Restrição por base de conhecimento: o token só enxerga as bases escolhidas; as outras respondem not_found, e ele não pode criar bases novas (forbidden).
  • Modelos prontos: ao criar a chave, "Somente leitura", "Agente de suporte" e "Agente completo" preenchem escopos e controles de uma vez.

Expiração, limite e bases podem ser alterados depois; os escopos, não. Para mudar escopos, crie outra chave.

Erros de autenticação

CódigoHTTPQuando
auth.missing_token401Header de autenticação não enviado.
auth.invalid_token401Token malformado.
auth.unauthorized401Token inválido, expirado ou revogado.
auth.email_not_verified403E-mail da conta ainda não verificado.
scope.missing403Token sem o escopo exigido pela rota (details.required, details.provided).
tool.disabled403A ferramenta ainda não está liberada para a conta: está desligada ou em testes com contas selecionadas. Ferramentas com código próprio (como rag.disabled) respondem com ele.
forbidden403A chave não pode fazer esta ação (ex.: chave restrita a bases de conhecimento específicas tentando criar uma base).

Dashboard vs. token de API

  • Dashboard — a navegação no painel não consome a franquia diária nem debita leituras medidas.
  • Token de API — leituras medidas compartilham a franquia diária de 2.000 requisições (4.000 em contas premium). Depois disso, cada leitura debita créditos.

Exemplo

Criar um QR com dry-run para validar o token, os escopos e o custo sem debitar nada:

curl -sS -X POST 'https://api.respawntech.dev/v1/tools/image/qr-code/dynamic' \
  -H "X-API-Token: $RESPAWN_API_TOKEN" \
  -H 'X-Dry-Run: true' \
  -H 'X-Include-Cost: true' \
  -H 'Content-Type: application/json' \
  -d '{
"name": "Campanha",
"target_url": "https://example.com"
}'
const response = await fetch('https://api.respawntech.dev/v1/tools/image/qr-code/dynamic', {
  method: 'POST',
  headers: {
    'X-API-Token': process.env.RESPAWN_API_TOKEN,
    'X-Dry-Run': 'true',
    'X-Include-Cost': 'true',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
"name": "Campanha",
"target_url": "https://example.com"
}),
});

if (!response.ok) throw new Error((await response.json()).error.code);
console.log(await response.json());
import os
import requests

response = requests.post(
    "https://api.respawntech.dev/v1/tools/image/qr-code/dynamic",
    headers={
        "X-API-Token": os.environ["RESPAWN_API_TOKEN"],
        "X-Dry-Run": "true",
        "X-Include-Cost": "true",
    },
    json={
"name": "Campanha",
"target_url": "https://example.com"
},
    timeout=30,
)
if not response.ok:
    raise RuntimeError(response.json()["error"]["code"])
print(response.json())
<?php
$ch = curl_init('https://api.respawntech.dev/v1/tools/image/qr-code/dynamic');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-API-Token: ' . getenv('RESPAWN_API_TOKEN'),
        'X-Dry-Run: true',
        'X-Include-Cost: true',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
"name": "Campanha",
"target_url": "https://example.com"
}
JSON,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status >= 400) {
    throw new RuntimeException(json_decode($body, true)['error']['code']);
}
print_r(json_decode($body, true));
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
	"time"
)

func main() {
	req, err := http.NewRequest("POST", "https://api.respawntech.dev/v1/tools/image/qr-code/dynamic", strings.NewReader(`{
"name": "Campanha",
"target_url": "https://example.com"
}`))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Token", os.Getenv("RESPAWN_API_TOKEN"))
	req.Header.Set("X-Dry-Run", "true")
	req.Header.Set("X-Include-Cost", "true")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 30 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	if res.StatusCode >= 400 {
		panic(string(data))
	}
	fmt.Println(string(data))
}

Atualizado em