Verificação de URL

Verifique se uma URL é maliciosa antes de exibi-la ou redirecionar usuários, e obtenha o favicon de um domínio sem expor o IP do cliente a terceiros.

Base path: /v1/tools/safety
Escopos: tools:safety:readtools:readtools:manage

Visão geral

Use antes de exibir links gerados por usuários ou de redirecionar alguém para um destino externo. É a mesma verificação que o QR Dinâmico aplica às URLs de destino.

Operação	Rota
Verificar URL	GET`/check`
Favicon de um domínio	GET`/favicon`

Custos

As duas operações são leituras medidas: entram na franquia diária e, depois dela, debitam o valor indicado em cada endpoint.

Endpoints

Verificar URL

GET/v1/tools/safety/check

Custo: Franquia diária, depois 0,01 crédito/leitura via API
Dry-run: Suportado (X-Dry-Run: true)
Autenticação: qualquer um detools:safety:readtools:readtools:manage

Query: url (obrigatório, URL absoluta). Resultados são mantidos em cache por 1 hora.

Resposta fora do envelope padrão

Esta rota responde { "is_safe": … } diretamente, sem success/data. Se o serviço de verificação estiver indisponível, a resposta é is_safe: true (fail-open), para não bloquear o seu fluxo. Em dry-run a resposta volta ao envelope padrão.

curl -sS -X GET 'https://api.respawntech.dev/v1/tools/safety/check?url=https%3A%2F%2Fexample.com' \
  -H "X-API-Token: $RESPAWN_API_TOKEN"

const response = await fetch('https://api.respawntech.dev/v1/tools/safety/check?url=https%3A%2F%2Fexample.com', {
  method: 'GET',
  headers: {
    'X-API-Token': process.env.RESPAWN_API_TOKEN,
  },
});

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

import os
import requests

response = requests.get(
    "https://api.respawntech.dev/v1/tools/safety/check?url=https%3A%2F%2Fexample.com",
    headers={
        "X-API-Token": os.environ["RESPAWN_API_TOKEN"],
    },
    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/safety/check?url=https%3A%2F%2Fexample.com');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'X-API-Token: ' . getenv('RESPAWN_API_TOKEN'),
    ],
    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"
	"time"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.respawntech.dev/v1/tools/safety/check?url=https%3A%2F%2Fexample.com", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Token", os.Getenv("RESPAWN_API_TOKEN"))

	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))
}

Resposta 200 — fora do envelope padrão

{
  "is_safe": true
}

Favicon de um domínio

GET/v1/tools/safety/favicon

Custo: Franquia diária, depois 0,002 crédito/leitura via API
Dry-run: Suportado (X-Dry-Run: true)
Autenticação: qualquer um detools:safety:readtools:readtools:manage

Query: domain (obrigatório).

curl -sS -X GET 'https://api.respawntech.dev/v1/tools/safety/favicon?domain=example.com' \
  -H "X-API-Token: $RESPAWN_API_TOKEN"

const response = await fetch('https://api.respawntech.dev/v1/tools/safety/favicon?domain=example.com', {
  method: 'GET',
  headers: {
    'X-API-Token': process.env.RESPAWN_API_TOKEN,
  },
});

if (!response.ok) throw new Error((await response.json()).error.code);
const file = Buffer.from(await response.arrayBuffer());

import os
import requests

response = requests.get(
    "https://api.respawntech.dev/v1/tools/safety/favicon?domain=example.com",
    headers={
        "X-API-Token": os.environ["RESPAWN_API_TOKEN"],
    },
    timeout=30,
)
if not response.ok:
    raise RuntimeError(response.json()["error"]["code"])
open("arquivo", "wb").write(response.content)

<?php
$ch = curl_init('https://api.respawntech.dev/v1/tools/safety/favicon?domain=example.com');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'X-API-Token: ' . getenv('RESPAWN_API_TOKEN'),
    ],
    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']);
}
file_put_contents('arquivo', $body);

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.respawntech.dev/v1/tools/safety/favicon?domain=example.com", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Token", os.Getenv("RESPAWN_API_TOKEN"))

	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))
	}
	if err := os.WriteFile("arquivo", data, 0o644); err != nil {
		panic(err)
	}
}

Resposta 200 — imagem binária (64×64) com o Content-Type original e Cache-Control: public, max-age=86400

Erros

Código	HTTP	Quando
`tools.safety.invalid_url`	400	Parâmetro `url` ausente ou inválido.
`tools.safety.domain_required`	400	Parâmetro `domain` ausente.
`tools.safety.favicon_not_found`	404	Favicon não encontrado para o domínio.