Ces endpoints retournent des données de risque au niveau du domaine. Ils nécessitent une clé API et chaque appel est décompté de votre quota mensuel.

:::note[Accès limité]
Ces endpoints sont actuellement en accès limité. Les patterns d'utilisation peuvent évoluer et le schéma de réponse peut changer dans les prochaines versions.
:::

---

## GET /v1/public/top-domains

Retourne une liste des domaines jetables ou risqués les plus fréquemment détectés.

### Authentification

```
Authorization: Bearer sv_votre_cle
```

### Requête

```bash
curl "https://api.syvel.io/v1/public/top-domains" \
  -H "Authorization: Bearer sv_votre_cle"
```

### Réponse

```json
{
  "domains": [
    {
      "domain": "yopmail.com",
      "risk_score": 100,
      "reason": "disposable"
    },
    {
      "domain": "guerrillamail.com",
      "risk_score": 100,
      "reason": "disposable"
    }
  ],
  "count": 100
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `domains` | array | Liste des domaines détectés |
| `domains[].domain` | string | Nom du domaine |
| `domains[].risk_score` | integer | Score de risque de 0 à 100 |
| `domains[].reason` | string | `disposable` · `undeliverable` · `role_account` |
| `count` | integer | Nombre total de domaines retournés |

---

## GET /v1/public/domain/{domain}

Retourne les informations de risque pour un domaine spécifique. N'effectue pas d'analyse de la partie locale (utilisez [GET /v1/check/{email_ou_domaine}](/fr/docs/api/check) pour une analyse complète d'email).

### Authentification

```
Authorization: Bearer sv_votre_cle
```

### Requête

```bash
curl "https://api.syvel.io/v1/public/domain/yopmail.com" \
  -H "Authorization: Bearer sv_votre_cle"
```

### Réponse

```json
{
  "domain": "yopmail.com",
  "risk_score": 100,
  "reason": "disposable",
  "is_free_provider": false,
  "is_corporate_email": false,
  "mx_provider_label": "Yopmail"
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `domain` | string | Le domaine interrogé |
| `risk_score` | integer | Score de risque de 0 à 100 — plus élevé = plus risqué |
| `reason` | string | `safe` · `disposable` · `undeliverable` · `role_account` |
| `is_free_provider` | boolean | `true` pour les webmails grand public |
| `is_corporate_email` | boolean | `true` pour les domaines avec une configuration MX professionnelle |
| `mx_provider_label` | string \| null | Nom lisible du provider MX |

---

## Codes d'erreur

| Code | Description |
|------|-------------|
| `401` | Clé API manquante ou invalide |
| `403` | Origine non autorisée |
| `422` | Format de domaine invalide |
| `429` | Quota dépassé — fail open |
| `500` | Erreur interne — fail open |

:::caution[Fail open]
Enveloppez toujours ces appels dans un `try/catch` avec un timeout. Si l'endpoint est indisponible, continuez votre logique applicative normalement.
:::