These endpoints return domain-level risk data. They require an API key and each call counts against your monthly quota.

:::note[Limited access]
These endpoints are currently in limited access. Usage patterns may evolve and the response schema may change in future versions.
:::

---

## GET /v1/public/top-domains

Returns a list of the most frequently flagged disposable or risky domains.

### Authentication

```
Authorization: Bearer sv_your_key
```

### Request

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

### Response

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

| Field | Type | Description |
|-------|------|-------------|
| `domains` | array | List of flagged domains |
| `domains[].domain` | string | Domain name |
| `domains[].risk_score` | integer | Risk score from 0 to 100 |
| `domains[].reason` | string | `disposable` · `undeliverable` · `role_account` |
| `count` | integer | Total number of domains returned |

---

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

Returns risk information for a specific domain. Does not perform local-part analysis (use [GET /v1/check/{email_or_domain}](/docs/api/check) for full email analysis).

### Authentication

```
Authorization: Bearer sv_your_key
```

### Request

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

### Response

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

| Field | Type | Description |
|-------|------|-------------|
| `domain` | string | The queried domain |
| `risk_score` | integer | Risk score from 0 to 100 — higher is riskier |
| `reason` | string | `safe` · `disposable` · `undeliverable` · `role_account` |
| `is_free_provider` | boolean | `true` for consumer webmail providers |
| `is_corporate_email` | boolean | `true` for domains with a professional MX configuration |
| `mx_provider_label` | string \| null | Human-readable MX provider name |

---

## Error codes

| Code | Description |
|------|-------------|
| `401` | Missing or invalid API key |
| `403` | Unauthorised origin |
| `422` | Invalid domain format |
| `429` | Quota exceeded — fail open |
| `500` | Internal server error — fail open |

:::caution[Fail open]
Always wrap these calls in a `try/catch` with a timeout. If the endpoint is unavailable, continue your application logic normally.
:::