> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/fr/docs/products/watchlist

# API Liste de Surveillance de Domaine

Gérez votre liste de surveillance de domaines. Recevez une notification lorsque les domaines deviennent disponibles ou changent de statut. Utilisez cette référence pour choisir le bon endpoint et voir exactement ce qu'il renvoie.

[Voir la page du produit](https://domscan.net/fr/watchlist-api)

## Opérations

GET `/v1/watchlist` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#getWatchlist)

POST `/v1/watchlist` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#addToWatchlist)

PATCH `/v1/watchlist/:domain` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#updateWatchlistDomain)

DELETE `/v1/watchlist` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#removeFromWatchlist)

GET `/v1/watchlist/expiring` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#getExpiringWatchlist)

GET `/v1/watchlist/available` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#getAvailableWatchlist)

GET `/v1/webhooks` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#listAlertWebhooks)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

POST `/v1/webhooks` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#createAlertWebhook)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

PATCH `/v1/webhooks/:webhook_id` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#updateAlertWebhook)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

DELETE `/v1/webhooks/:webhook_id` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#deleteAlertWebhook)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

POST `/v1/webhooks/:webhook_id/test` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#testAlertWebhook)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

POST `/v1/webhooks/:webhook_id/rotate-secret` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#rotateAlertWebhookSecret)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

GET `/v1/webhooks/:webhook_id/deliveries` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#listAlertWebhookDeliveries)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

GET `/v1/watchlist/alerts` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#listWatchlistAlerts)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

POST `/v1/watchlist/alerts` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#createWatchlistAlert)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

GET `/v1/watchlist/alerts/:subscription_id` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#getWatchlistAlert)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

PATCH `/v1/watchlist/alerts/:subscription_id` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#updateWatchlistAlert)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

DELETE `/v1/watchlist/alerts/:subscription_id` [Voir la référence API](https://domscan.net/fr/docs/products/watchlist#deleteWatchlistAlert)[Lire le guide](https://domscan.net/fr/webhook-alerts-api)

## GET `/v1/watchlist`

Opération: `getWatchlist`
Crédits et authentification: 1
Authentification requise

GET /v1/watchlist Crédits: 1

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| limit | integer | optionnel |
| cursor | string | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `watchlist[]` | object[] |
| `watchlist[]` | object |
| `watchlist[].domain` | string |
| `watchlist[].added_at` | string |
| `watchlist[].status` | string |
| `watchlist[].last_checked` | string |
| `watchlist[].expiry_date` | string |
| `watchlist[].days_until_expiry` | integer |
| `watchlist[].notify_email` | string |
| `watchlist[].check_count` | integer |
| `total` | integer |
| `max_domains` | integer |
| `limit_basis` | string |
| `updated_at` | string |

#### Exemple de requête

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/watchlist"
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/watchlist",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/watchlist", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Exemple de réponse

```json
{
  "watchlist": [
    {
      "domain": "example.com",
      "added_at": "2024-01-01T00:00:00Z",
      "status": "registered",
      "last_checked": "2024-01-15T12:00:00Z"
    }
  ],
  "total": 1,
  "max_domains": 333,
  "limit_basis": "monthly_credits",
  "updated_at": "2024-01-15T12:00:00Z"
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `402` Paiement requis
- `429` Trop de requêtes

## POST `/v1/watchlist`

Opération: `addToWatchlist`
Crédits et authentification: 1
Authentification requise

POST /v1/watchlist Crédits: 1

#### Paramètres du corps

| Paramètre | Type | requis |
| --- | --- | --- |
| domain | string | requis |
| notify_email | string | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `success` | boolean |
| `message` | string |
| `watchlist[]` | object[] |
| `watchlist[]` | object |
| `watchlist[].domain` | string |
| `watchlist[].added_at` | string |
| `watchlist[].status` | string |
| `watchlist[].last_checked` | string |
| `watchlist[].expiry_date` | string |
| `watchlist[].days_until_expiry` | integer |
| `watchlist[].notify_email` | string |
| `watchlist[].check_count` | integer |
| `total` | integer |
| `max_domains` | integer |
| `limit_basis` | string |

#### Exemple de requête

```bash
curl -X POST "https://domscan.net/v1/watchlist" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "domain": "example.org",
  "notify_email": "alerts@example.com"
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "domain": "example.org",
    "notify_email": "alerts@example.com"
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/watchlist",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "domain": "example.org",
        "notify_email": "alerts@example.com",
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "domain": "example.org",
	  "notify_email": "alerts@example.com"
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/watchlist", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "domain" => "example.org",
  "notify_email" => "alerts@example.com"
})

#### Exemple de réponse

```json
{
  "success": true,
  "message": "Added example.org to watchlist",
  "watchlist": [
    {
      "domain": "example.com",
      "added_at": "2026-06-02T09:12:00.000Z",
      "last_checked": "2026-10-09T03:00:12.000Z",
      "status": "expiring_soon",
      "expiry_date": "2026-12-18T14:22:08Z",
      "days_until_expiry": 70,
      "notify_email": "alerts@example.com"
    },
    {
      "domain": "example.org",
      "added_at": "2026-10-09T10:15:30.000Z",
      "status": "unknown",
      "notify_email": "alerts@example.com"
    }
  ],
  "total": 2,
  "max_domains": 333,
  "limit_basis": "monthly_credits"
}
```

#### Codes de statut HTTP

- `201` Créé
- `400` Requête incorrecte
- `401` Non autorisé
- `402` Paiement requis
- `409` HTTP 409
- `422` HTTP 422
- `429` Trop de requêtes

## PATCH `/v1/watchlist/:domain`

Opération: `updateWatchlistDomain`
Crédits et authentification: Gratuit
Authentification requise

PATCH /v1/watchlist/:domain Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| domain | string | requis |

#### Paramètres du corps

| Paramètre | Type | requis |
| --- | --- | --- |
| notify_email | string \| null | requis |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `success` | boolean |
| `message` | string |
| `domain` | object |
| `domain.domain` | string |
| `domain.added_at` | string |
| `domain.status` | string |
| `domain.last_checked` | string |
| `domain.expiry_date` | string |
| `domain.days_until_expiry` | integer |
| `domain.notify_email` | string |
| `domain.check_count` | integer |

#### Exemple de requête

```bash
curl -X PATCH "https://domscan.net/v1/watchlist/example.com" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "notify_email": "ops@example.com"
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/example.com", {
  method: "PATCH",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "notify_email": "ops@example.com"
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.patch(
    "https://domscan.net/v1/watchlist/example.com",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "notify_email": "ops@example.com",
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "notify_email": "ops@example.com"
	}`)
	req, err := http.NewRequest(http.MethodPatch, "https://domscan.net/v1/watchlist/example.com", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/example.com")
request = Net::HTTP::Patch.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "notify_email" => "ops@example.com"
})

#### Exemple de réponse

```json
{
  "success": true,
  "message": "Updated example.com in your watchlist",
  "domain": {
    "domain": "example.com",
    "added_at": "2026-06-02T09:12:00.000Z",
    "status": "registered",
    "notify_email": "ops@example.com",
    "check_count": 12
  }
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## DELETE `/v1/watchlist`

Opération: `removeFromWatchlist`
Crédits et authentification: Gratuit
Authentification requise

DELETE /v1/watchlist Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| domain | string | requis |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `success` | boolean |
| `message` | string |
| `domain` | string |
| `watchlist[]` | object[] |
| `watchlist[]` | object |
| `watchlist[].domain` | string |
| `watchlist[].added_at` | string |
| `watchlist[].status` | string |
| `watchlist[].last_checked` | string |
| `watchlist[].expiry_date` | string |
| `watchlist[].days_until_expiry` | integer |
| `watchlist[].notify_email` | string |
| `watchlist[].check_count` | integer |
| `total` | integer |

#### Exemple de requête

```bash
curl -X DELETE "https://domscan.net/v1/watchlist?domain=example.com" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist?domain=example.com", {
  method: "DELETE",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.delete(
    "https://domscan.net/v1/watchlist?domain=example.com",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={},
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{}`)
	req, err := http.NewRequest(http.MethodDelete, "https://domscan.net/v1/watchlist?domain=example.com", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist?domain=example.com")
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({})

#### Exemple de réponse

```json
{
  "success": true,
  "message": "Request completed",
  "domain": "example.com",
  "watchlist": [
    {
      "domain": "example.com",
      "added_at": "2026-08-27T12:00:00Z",
      "status": "registered",
      "last_checked": "2026-08-27T12:00:00Z",
      "expiry_date": "2026-08-27T12:00:00Z",
      "days_until_expiry": 1,
      "notify_email": "user@example.com",
      "check_count": 1
    }
  ],
  "total": 1
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `402` Paiement requis
- `429` Trop de requêtes

## GET `/v1/watchlist/expiring`

Opération: `getExpiringWatchlist`
Crédits et authentification: 1
Authentification requise

GET /v1/watchlist/expiring Crédits: 1

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| days | integer Défaut `90` | optionnel |
| limit | integer | optionnel |
| cursor | string | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `expiring_domains[]` | object[] |
| `expiring_domains[]` | object |
| `expiring_domains[].domain` | string |
| `expiring_domains[].added_at` | string |
| `expiring_domains[].status` | string |
| `expiring_domains[].last_checked` | string |
| `expiring_domains[].expiry_date` | string |
| `expiring_domains[].days_until_expiry` | integer |
| `expiring_domains[].notify_email` | string |
| `expiring_domains[].check_count` | integer |
| `total` | integer |
| `threshold_days` | integer |

#### Exemple de requête

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/watchlist/expiring?days=90"
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/expiring?days=90", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/watchlist/expiring?days=90",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/watchlist/expiring?days=90", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/expiring?days=90")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Exemple de réponse

```json
{
  "expiring_domains": [
    {
      "domain": "example.com",
      "added_at": "2026-06-02T09:12:00.000Z",
      "last_checked": "2026-10-09T03:00:12.000Z",
      "status": "expiring_soon",
      "expiry_date": "2026-12-18T14:22:08Z",
      "days_until_expiry": 70,
      "notify_email": "alerts@example.com"
    }
  ],
  "total": 1,
  "threshold_days": 90
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `402` Paiement requis
- `429` Trop de requêtes

## GET `/v1/watchlist/available`

Opération: `getAvailableWatchlist`
Crédits et authentification: 1
Authentification requise

GET /v1/watchlist/available Crédits: 1

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| limit | integer | optionnel |
| cursor | string | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `has_more` | boolean |
| `next_cursor` | string \| null |
| `available_domains[]` | object[] |
| `available_domains[]` | object |
| `available_domains[].domain` | string |
| `available_domains[].added_at` | string |
| `available_domains[].status` | string |
| `available_domains[].last_checked` | string |
| `available_domains[].expiry_date` | string |
| `available_domains[].days_until_expiry` | integer |
| `available_domains[].notify_email` | string |
| `available_domains[].check_count` | integer |
| `total` | integer |
| `message` | string |

#### Exemple de requête

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/watchlist/available"
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/available", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/watchlist/available",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/watchlist/available", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/available")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Exemple de réponse

```json
{
  "has_more": false,
  "next_cursor": "example",
  "available_domains": [
    {
      "domain": "example.com",
      "added_at": "2026-08-27T12:00:00Z",
      "status": "registered",
      "last_checked": "2026-08-27T12:00:00Z",
      "expiry_date": "2026-08-27T12:00:00Z",
      "days_until_expiry": 1,
      "notify_email": "user@example.com",
      "check_count": 1
    }
  ],
  "total": 1,
  "message": "Request completed"
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `402` Paiement requis
- `429` Trop de requêtes

## GET `/v1/webhooks`

Opération: `listAlertWebhooks`
Crédits et authentification: Gratuit
Authentification requise

GET /v1/webhooks Crédits: 0

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `endpoints[]` | object[] |
| `endpoints[]` | object |
| `endpoints[].id` | string |
| `endpoints[].url` | string |
| `endpoints[].description` | string \| null |
| `endpoints[].events[]` | string[] |
| `endpoints[].status` | string |
| `endpoints[].disabled_reason` | string \| null |
| `endpoints[].consecutive_failures` | integer |
| `endpoints[].secret_hint` | string |
| `endpoints[].previous_secret_expires_at` | string \| null |
| `endpoints[].secret_rotated_at` | string \| null |
| `endpoints[].last_success_at` | string \| null |
| `endpoints[].last_failure_at` | string \| null |
| `endpoints[].last_error` | string \| null |
| `endpoints[].created_at` | string |
| `endpoints[].updated_at` | string |
| `endpoints[].disabled_at` | string \| null |
| `available_events[]` | string[] |
| `all_events` | string |
| `test_event` | string |
| `policy` | object |
| `policy.secret_rotation_grace_seconds` | integer |
| `policy.secret_rotation_credits` | integer |
| `policy.credits_per_delivered_alert` | integer |
| `policy.test_event_credits` | integer |
| `policy.job_event_credits` | integer |
| `policy.failed_deliveries_charged` | boolean |
| `policy.max_endpoints` | integer |
| `policy.max_attempts` | integer |
| `policy.disable_after_consecutive_failures` | integer |
| `policy.signature_tolerance_seconds` | integer |

#### Exemple de requête

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/webhooks"
```

```javascript
const response = await fetch("https://domscan.net/v1/webhooks", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/webhooks",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/webhooks", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/webhooks")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Exemple de réponse

```json
{
  "endpoints": [
    {
      "id": "example-id",
      "url": "https://example.com",
      "events": [
        "example"
      ],
      "status": "active",
      "secret_hint": "example",
      "created_at": "2026-08-27T12:00:00Z",
      "description": "example",
      "disabled_reason": "customer",
      "consecutive_failures": 1,
      "previous_secret_expires_at": "2026-08-27T12:00:00Z",
      "secret_rotated_at": "2026-08-27T12:00:00Z",
      "last_success_at": "2026-08-27T12:00:00Z",
      "last_failure_at": "2026-08-27T12:00:00Z",
      "last_error": "example",
      "updated_at": "2026-08-27T12:00:00Z",
      "disabled_at": "2026-08-27T12:00:00Z"
    }
  ],
  "available_events": [
    "domain.available"
  ],
  "policy": {
    "credits_per_delivered_alert": 2,
    "test_event_credits": 0,
    "failed_deliveries_charged": false,
    "max_endpoints": 1,
    "max_attempts": 1,
    "disable_after_consecutive_failures": 1,
    "signature_tolerance_seconds": 1,
    "secret_rotation_grace_seconds": 86400,
    "secret_rotation_credits": 0,
    "job_event_credits": 0
  },
  "all_events": "*",
  "test_event": "webhook.test"
}
```

#### Codes de statut HTTP

- `200` OK
- `401` Non autorisé
- `429` Trop de requêtes

## POST `/v1/webhooks`

Opération: `createAlertWebhook`
Crédits et authentification: Gratuit
Authentification requise

POST /v1/webhooks Crédits: 0

#### Paramètres du corps

| Paramètre | Type | requis |
| --- | --- | --- |
| url | string | requis |
| description | string \| null | optionnel |
| events | unknown[] | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `endpoint` | object |
| `endpoint.id` | string |
| `endpoint.url` | string |
| `endpoint.description` | string \| null |
| `endpoint.events[]` | string[] |
| `endpoint.status` | string |
| `endpoint.disabled_reason` | string \| null |
| `endpoint.consecutive_failures` | integer |
| `endpoint.secret_hint` | string |
| `endpoint.previous_secret_expires_at` | string \| null |
| `endpoint.secret_rotated_at` | string \| null |
| `endpoint.last_success_at` | string \| null |
| `endpoint.last_failure_at` | string \| null |
| `endpoint.last_error` | string \| null |
| `endpoint.created_at` | string |
| `endpoint.updated_at` | string |
| `endpoint.disabled_at` | string \| null |
| `secret` | string |

#### Exemple de requête

```bash
curl -X POST "https://domscan.net/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "url": "https://hooks.example.com/domscan",
  "description": "Production alerts",
  "events": [
    "domain.expiring_30",
    "domain.available",
    "domain.dns_changed"
  ]
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/webhooks", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "url": "https://hooks.example.com/domscan",
    "description": "Production alerts",
    "events": [
      "domain.expiring_30",
      "domain.available",
      "domain.dns_changed"
    ]
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/webhooks",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "url": "https://hooks.example.com/domscan",
        "description": "Production alerts",
        "events": [
            "domain.expiring_30",
            "domain.available",
            "domain.dns_changed",
        ],
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "url": "https://hooks.example.com/domscan",
	  "description": "Production alerts",
	  "events": [
	    "domain.expiring_30",
	    "domain.available",
	    "domain.dns_changed"
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/webhooks", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/webhooks")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "url" => "https://hooks.example.com/domscan",
  "description" => "Production alerts",
  "events" => [
    "domain.expiring_30",
    "domain.available",
    "domain.dns_changed"
  ]
})

#### Exemple de réponse

```json
{
  "endpoint": {
    "id": "example-id",
    "url": "https://example.com",
    "events": [
      "example"
    ],
    "status": "active",
    "secret_hint": "example",
    "created_at": "2026-08-27T12:00:00Z",
    "description": "example",
    "disabled_reason": "customer",
    "consecutive_failures": 1,
    "previous_secret_expires_at": "2026-08-27T12:00:00Z",
    "secret_rotated_at": "2026-08-27T12:00:00Z",
    "last_success_at": "2026-08-27T12:00:00Z",
    "last_failure_at": "2026-08-27T12:00:00Z",
    "last_error": "example",
    "updated_at": "2026-08-27T12:00:00Z",
    "disabled_at": "2026-08-27T12:00:00Z"
  },
  "secret": "example"
}
```

#### Codes de statut HTTP

- `201` Créé
- `400` Requête incorrecte
- `401` Non autorisé
- `409` HTTP 409
- `429` Trop de requêtes

## PATCH `/v1/webhooks/:webhook_id`

Opération: `updateAlertWebhook`
Crédits et authentification: Gratuit
Authentification requise

PATCH /v1/webhooks/:webhook_id Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| webhook_id | string | requis |

#### Paramètres du corps

| Paramètre | Type | requis |
| --- | --- | --- |
| enabled | boolean | optionnel |
| description | string \| null | optionnel |
| events | unknown[] | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `endpoint` | object |
| `endpoint.id` | string |
| `endpoint.url` | string |
| `endpoint.description` | string \| null |
| `endpoint.events[]` | string[] |
| `endpoint.status` | string |
| `endpoint.disabled_reason` | string \| null |
| `endpoint.consecutive_failures` | integer |
| `endpoint.secret_hint` | string |
| `endpoint.previous_secret_expires_at` | string \| null |
| `endpoint.secret_rotated_at` | string \| null |
| `endpoint.last_success_at` | string \| null |
| `endpoint.last_failure_at` | string \| null |
| `endpoint.last_error` | string \| null |
| `endpoint.created_at` | string |
| `endpoint.updated_at` | string |
| `endpoint.disabled_at` | string \| null |

#### Exemple de requête

```bash
curl -X PATCH "https://domscan.net/v1/webhooks/string" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "enabled": true,
  "events": [
    "*"
  ]
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/webhooks/string", {
  method: "PATCH",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "enabled": true,
    "events": [
      "*"
    ]
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.patch(
    "https://domscan.net/v1/webhooks/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "enabled": True,
        "events": [
            "*",
        ],
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "enabled": true,
	  "events": [
	    "*"
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPatch, "https://domscan.net/v1/webhooks/string", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/webhooks/string")
request = Net::HTTP::Patch.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "enabled" => true,
  "events" => [
    "*"
  ]
})

#### Exemple de réponse

```json
{
  "endpoint": {
    "id": "example-id",
    "url": "https://example.com",
    "events": [
      "example"
    ],
    "status": "active",
    "secret_hint": "example",
    "created_at": "2026-08-27T12:00:00Z",
    "description": "example",
    "disabled_reason": "customer",
    "consecutive_failures": 1,
    "previous_secret_expires_at": "2026-08-27T12:00:00Z",
    "secret_rotated_at": "2026-08-27T12:00:00Z",
    "last_success_at": "2026-08-27T12:00:00Z",
    "last_failure_at": "2026-08-27T12:00:00Z",
    "last_error": "example",
    "updated_at": "2026-08-27T12:00:00Z",
    "disabled_at": "2026-08-27T12:00:00Z"
  }
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## DELETE `/v1/webhooks/:webhook_id`

Opération: `deleteAlertWebhook`
Crédits et authentification: Gratuit
Authentification requise

DELETE /v1/webhooks/:webhook_id Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| webhook_id | string | requis |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `id` | string |
| `deleted` | boolean |

#### Exemple de requête

```bash
curl -X DELETE "https://domscan.net/v1/webhooks/string" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'
```

```javascript
const response = await fetch("https://domscan.net/v1/webhooks/string", {
  method: "DELETE",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.delete(
    "https://domscan.net/v1/webhooks/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={},
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{}`)
	req, err := http.NewRequest(http.MethodDelete, "https://domscan.net/v1/webhooks/string", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/webhooks/string")
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({})

#### Exemple de réponse

```json
{
  "id": "example-id",
  "deleted": true
}
```

#### Codes de statut HTTP

- `200` OK
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## POST `/v1/webhooks/:webhook_id/test`

Opération: `testAlertWebhook`
Crédits et authentification: Gratuit
Authentification requise

POST /v1/webhooks/:webhook_id/test Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| webhook_id | string | requis |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `delivery` | object |
| `delivery.id` | string |
| `delivery.endpoint_id` | string |
| `delivery.event_id` | string |
| `delivery.event_type` | string |
| `delivery.status` | string |
| `delivery.attempts` | integer |
| `delivery.next_attempt_at` | string \| null |
| `delivery.last_attempt_at` | string \| null |
| `delivery.response_status` | integer \| null |
| `delivery.last_error` | string \| null |
| `delivery.credits_charged` | integer |
| `delivery.refunded` | boolean |
| `delivery.created_at` | string |
| `delivery.delivered_at` | string \| null |
| `delivered` | boolean |

#### Exemple de requête

```bash
curl -X POST "https://domscan.net/v1/webhooks/string/test" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'
```

```javascript
const response = await fetch("https://domscan.net/v1/webhooks/string/test", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/webhooks/string/test",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={},
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/webhooks/string/test", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/webhooks/string/test")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({})

#### Exemple de réponse

```json
{
  "delivery": {
    "id": "example-id",
    "endpoint_id": "example",
    "event_id": "example",
    "event_type": "domain",
    "status": "pending",
    "attempts": 1,
    "next_attempt_at": "2026-08-27T12:00:00Z",
    "last_attempt_at": "2026-08-27T12:00:00Z",
    "response_status": 1,
    "last_error": "example",
    "credits_charged": 1,
    "refunded": false,
    "created_at": "2026-08-27T12:00:00Z",
    "delivered_at": "2026-08-27T12:00:00Z"
  },
  "delivered": false
}
```

#### Codes de statut HTTP

- `200` OK
- `401` Non autorisé
- `404` Introuvable
- `409` HTTP 409
- `429` Trop de requêtes

## POST `/v1/webhooks/:webhook_id/rotate-secret`

Opération: `rotateAlertWebhookSecret`
Crédits et authentification: Gratuit
Authentification requise

POST /v1/webhooks/:webhook_id/rotate-secret Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| webhook_id | string | requis |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `endpoint` | object |
| `endpoint.id` | string |
| `endpoint.url` | string |
| `endpoint.description` | string \| null |
| `endpoint.events[]` | string[] |
| `endpoint.status` | string |
| `endpoint.disabled_reason` | string \| null |
| `endpoint.consecutive_failures` | integer |
| `endpoint.secret_hint` | string |
| `endpoint.previous_secret_expires_at` | string \| null |
| `endpoint.secret_rotated_at` | string \| null |
| `endpoint.last_success_at` | string \| null |
| `endpoint.last_failure_at` | string \| null |
| `endpoint.last_error` | string \| null |
| `endpoint.created_at` | string |
| `endpoint.updated_at` | string |
| `endpoint.disabled_at` | string \| null |
| `secret` | string |
| `previous_secret_expires_at` | string |
| `grace_period_seconds` | integer |

#### Exemple de requête

```bash
curl -X POST "https://domscan.net/v1/webhooks/string/rotate-secret" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'
```

```javascript
const response = await fetch("https://domscan.net/v1/webhooks/string/rotate-secret", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/webhooks/string/rotate-secret",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={},
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/webhooks/string/rotate-secret", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/webhooks/string/rotate-secret")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({})

#### Exemple de réponse

```json
{
  "endpoint": {
    "id": "whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3",
    "url": "https://hooks.example.com/domscan",
    "events": [
      "*"
    ],
    "status": "active",
    "secret_hint": "4b7a",
    "previous_secret_expires_at": "2026-10-11T12:00:00.000Z",
    "secret_rotated_at": "2026-10-10T12:00:00.000Z",
    "created_at": "2026-10-01T09:30:00.000Z"
  },
  "secret": "whsec_...",
  "previous_secret_expires_at": "2026-10-11T12:00:00.000Z",
  "grace_period_seconds": 86400
}
```

#### Codes de statut HTTP

- `200` OK
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## GET `/v1/webhooks/:webhook_id/deliveries`

Opération: `listAlertWebhookDeliveries`
Crédits et authentification: Gratuit
Authentification requise

GET /v1/webhooks/:webhook_id/deliveries Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| webhook_id | string | requis |
| limit | integer Défaut `50` | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `endpoint_id` | string |
| `deliveries[]` | object[] |
| `deliveries[]` | object |
| `deliveries[].id` | string |
| `deliveries[].endpoint_id` | string |
| `deliveries[].event_id` | string |
| `deliveries[].event_type` | string |
| `deliveries[].status` | string |
| `deliveries[].attempts` | integer |
| `deliveries[].next_attempt_at` | string \| null |
| `deliveries[].last_attempt_at` | string \| null |
| `deliveries[].response_status` | integer \| null |
| `deliveries[].last_error` | string \| null |
| `deliveries[].credits_charged` | integer |
| `deliveries[].refunded` | boolean |
| `deliveries[].created_at` | string |
| `deliveries[].delivered_at` | string \| null |

#### Exemple de requête

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/webhooks/string/deliveries?limit=25"
```

```javascript
const response = await fetch("https://domscan.net/v1/webhooks/string/deliveries?limit=25", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/webhooks/string/deliveries?limit=25",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/webhooks/string/deliveries?limit=25", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/webhooks/string/deliveries?limit=25")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Exemple de réponse

```json
{
  "endpoint_id": "example",
  "deliveries": [
    {
      "id": "example-id",
      "endpoint_id": "example",
      "event_id": "example",
      "event_type": "domain",
      "status": "pending",
      "attempts": 1,
      "next_attempt_at": "2026-08-27T12:00:00Z",
      "last_attempt_at": "2026-08-27T12:00:00Z",
      "response_status": 1,
      "last_error": "example",
      "credits_charged": 1,
      "refunded": false,
      "created_at": "2026-08-27T12:00:00Z",
      "delivered_at": "2026-08-27T12:00:00Z"
    }
  ]
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## GET `/v1/watchlist/alerts`

Opération: `listWatchlistAlerts`
Crédits et authentification: Gratuit
Authentification requise

GET /v1/watchlist/alerts Crédits: 0

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `subscriptions[]` | object[] |
| `subscriptions[]` | object |
| `subscriptions[].id` | string |
| `subscriptions[].type` | string |
| `subscriptions[].target` | string |
| `subscriptions[].registrar` | string \| null |
| `subscriptions[].events[]` | string[] |
| `subscriptions[].status` | string |
| `subscriptions[].ssl_expiring_days` | integer \| null |
| `subscriptions[].price_type` | string \| null |
| `subscriptions[].drop_percent` | number \| null |
| `subscriptions[].target_price` | number \| null |
| `subscriptions[].currency` | string \| null |
| `subscriptions[].record_types[]` | string[] |
| `subscriptions[].attributes[]` | string[] |
| `subscriptions[].notify_email` | string \| null |
| `subscriptions[].observed` | object \| null |
| `subscriptions[].last_check_at` | string \| null |
| `subscriptions[].last_check_status` | string \| null |
| `subscriptions[].last_error` | string \| null |
| `subscriptions[].next_check_at` | string \| null |
| `subscriptions[].created_at` | string |
| `subscriptions[].updated_at` | string |
| `total` | integer |
| `available_types` | object |
| `available_types.ssl[]` | string[] |
| `available_types.price[]` | string[] |
| `available_types.dns[]` | string[] |
| `available_types.typosquat[]` | string[] |
| `available_types.brand[]` | string[] |
| `policy` | object |
| `policy.credits_per_delivered_alert` | integer |
| `policy.check_credits` | integer |
| `policy.unknown_checks_charged` | boolean |
| `policy.max_subscriptions` | integer |
| `policy.max_typosquat_subscriptions` | integer |
| `policy.max_brand_subscriptions` | integer |
| `policy.brand_attributes[]` | string[] |
| `policy.ssl_expiring_days[]` | integer[] |
| `policy.default_ssl_expiring_days` | integer |
| `policy.record_types[]` | string[] |
| `policy.price_types[]` | string[] |
| `policy.check_interval_minutes` | object |
| `policy.confirmation_checks` | object |

#### Exemple de requête

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/watchlist/alerts"
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/alerts", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/watchlist/alerts",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/watchlist/alerts", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/alerts")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Exemple de réponse

```json
{
  "subscriptions": [
    {
      "id": "example-id",
      "type": "ssl",
      "target": "example",
      "registrar": "example",
      "events": [
        "ssl.expiring"
      ],
      "status": "active",
      "ssl_expiring_days": 30,
      "price_type": "registration",
      "drop_percent": 0.5,
      "target_price": 0.5,
      "currency": "USD",
      "record_types": [
        "A"
      ],
      "attributes": [
        "logo"
      ],
      "notify_email": "user@example.com",
      "observed": {},
      "last_check_at": "2026-08-27T12:00:00Z",
      "last_check_status": "baseline",
      "last_error": "example",
      "next_check_at": "2026-08-27T12:00:00Z",
      "created_at": "2026-08-27T12:00:00Z",
      "updated_at": "2026-08-27T12:00:00Z"
    }
  ],
  "total": 1,
  "available_types": {
    "ssl": [
      "ssl.expiring"
    ],
    "price": [
      "price.dropped"
    ],
    "dns": [
      "dns.changed"
    ],
    "typosquat": [
      "typosquat.detected"
    ],
    "brand": [
      "brand.updated"
    ]
  },
  "policy": {
    "credits_per_delivered_alert": 2,
    "check_credits": 0,
    "unknown_checks_charged": false,
    "max_subscriptions": 1,
    "check_interval_minutes": {},
    "max_typosquat_subscriptions": 1,
    "max_brand_subscriptions": 1,
    "brand_attributes": [
      "logo"
    ],
    "ssl_expiring_days": [
      1
    ],
    "default_ssl_expiring_days": 1,
    "record_types": [
      "A"
    ],
    "price_types": [
      "registration"
    ],
    "confirmation_checks": {}
  }
}
```

#### Codes de statut HTTP

- `200` OK
- `401` Non autorisé
- `429` Trop de requêtes

## POST `/v1/watchlist/alerts`

Opération: `createWatchlistAlert`
Crédits et authentification: Gratuit
Authentification requise

POST /v1/watchlist/alerts Crédits: 0

#### Paramètres du corps

| Paramètre | Type | requis |
| --- | --- | --- |
| type | string Valeurs autorisées `ssl`, `price`, `dns`, `typosquat`, `brand` | requis |
| domain | string | optionnel |
| tld | string | optionnel |
| registrar | string \| null | optionnel |
| events | string[] Valeurs autorisées `ssl.expiring`, `ssl.expired`, `ssl.changed`, `price.dropped`, `dns.changed`, `typosquat.detected`, `brand.updated` | optionnel |
| ssl_expiring_days | integer Valeurs autorisées `30`, `14`, `7`, `1` Défaut `14` | optionnel |
| price_type | string Valeurs autorisées `registration`, `renewal` Défaut `registration` | optionnel |
| drop_percent | number \| null | optionnel |
| target_price | number \| null | optionnel |
| record_types | string[] Valeurs autorisées `A`, `AAAA`, `MX`, `NS`, `TXT`, `CNAME` | optionnel |
| attributes | string[] Valeurs autorisées `logo`, `wide_logo`, `colors`, `name`, `socials` | optionnel |
| notify_email | string \| null | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `subscription` | object |
| `subscription.id` | string |
| `subscription.type` | string |
| `subscription.target` | string |
| `subscription.registrar` | string \| null |
| `subscription.events[]` | string[] |
| `subscription.status` | string |
| `subscription.ssl_expiring_days` | integer \| null |
| `subscription.price_type` | string \| null |
| `subscription.drop_percent` | number \| null |
| `subscription.target_price` | number \| null |
| `subscription.currency` | string \| null |
| `subscription.record_types[]` | string[] |
| `subscription.attributes[]` | string[] |
| `subscription.notify_email` | string \| null |
| `subscription.observed` | object \| null |
| `subscription.last_check_at` | string \| null |
| `subscription.last_check_status` | string \| null |
| `subscription.last_error` | string \| null |
| `subscription.next_check_at` | string \| null |
| `subscription.created_at` | string |
| `subscription.updated_at` | string |

#### Exemple de requête

```bash
curl -X POST "https://domscan.net/v1/watchlist/alerts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "type": "ssl",
  "domain": "shop.example.com",
  "events": [
    "ssl.expiring",
    "ssl.changed"
  ],
  "ssl_expiring_days": 14
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/alerts", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "type": "ssl",
    "domain": "shop.example.com",
    "events": [
      "ssl.expiring",
      "ssl.changed"
    ],
    "ssl_expiring_days": 14
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/watchlist/alerts",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "type": "ssl",
        "domain": "shop.example.com",
        "events": [
            "ssl.expiring",
            "ssl.changed",
        ],
        "ssl_expiring_days": 14,
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "type": "ssl",
	  "domain": "shop.example.com",
	  "events": [
	    "ssl.expiring",
	    "ssl.changed"
	  ],
	  "ssl_expiring_days": 14
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/watchlist/alerts", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/alerts")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "type" => "ssl",
  "domain" => "shop.example.com",
  "events" => [
    "ssl.expiring",
    "ssl.changed"
  ],
  "ssl_expiring_days" => 14
})

#### Exemple de réponse

```json
{
  "subscription": {
    "id": "example-id",
    "type": "ssl",
    "target": "example",
    "registrar": "example",
    "events": [
      "ssl.expiring"
    ],
    "status": "active",
    "ssl_expiring_days": 30,
    "price_type": "registration",
    "drop_percent": 0.5,
    "target_price": 0.5,
    "currency": "USD",
    "record_types": [
      "A"
    ],
    "attributes": [
      "logo"
    ],
    "notify_email": "user@example.com",
    "observed": {},
    "last_check_at": "2026-08-27T12:00:00Z",
    "last_check_status": "baseline",
    "last_error": "example",
    "next_check_at": "2026-08-27T12:00:00Z",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z"
  }
}
```

#### Codes de statut HTTP

- `201` Créé
- `400` Requête incorrecte
- `401` Non autorisé
- `409` HTTP 409
- `429` Trop de requêtes

## GET `/v1/watchlist/alerts/:subscription_id`

Opération: `getWatchlistAlert`
Crédits et authentification: Gratuit
Authentification requise

GET /v1/watchlist/alerts/:subscription_id Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| subscription_id | string | requis |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `subscription` | object |
| `subscription.id` | string |
| `subscription.type` | string |
| `subscription.target` | string |
| `subscription.registrar` | string \| null |
| `subscription.events[]` | string[] |
| `subscription.status` | string |
| `subscription.ssl_expiring_days` | integer \| null |
| `subscription.price_type` | string \| null |
| `subscription.drop_percent` | number \| null |
| `subscription.target_price` | number \| null |
| `subscription.currency` | string \| null |
| `subscription.record_types[]` | string[] |
| `subscription.attributes[]` | string[] |
| `subscription.notify_email` | string \| null |
| `subscription.observed` | object \| null |
| `subscription.last_check_at` | string \| null |
| `subscription.last_check_status` | string \| null |
| `subscription.last_error` | string \| null |
| `subscription.next_check_at` | string \| null |
| `subscription.created_at` | string |
| `subscription.updated_at` | string |
| `events[]` | object[] |
| `events[]` | object |
| `events[].id` | string |
| `events[].event_type` | string |
| `events[].detected_at` | string |
| `events[].published_at` | string \| null |
| `events[].data` | object |

#### Exemple de requête

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/watchlist/alerts/string"
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/alerts/string", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/watchlist/alerts/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

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

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/watchlist/alerts/string", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/alerts/string")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### Exemple de réponse

```json
{
  "subscription": {
    "id": "example-id",
    "type": "ssl",
    "target": "example",
    "registrar": "example",
    "events": [
      "ssl.expiring"
    ],
    "status": "active",
    "ssl_expiring_days": 30,
    "price_type": "registration",
    "drop_percent": 0.5,
    "target_price": 0.5,
    "currency": "USD",
    "record_types": [
      "A"
    ],
    "attributes": [
      "logo"
    ],
    "notify_email": "user@example.com",
    "observed": {},
    "last_check_at": "2026-08-27T12:00:00Z",
    "last_check_status": "baseline",
    "last_error": "example",
    "next_check_at": "2026-08-27T12:00:00Z",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z"
  },
  "events": [
    {
      "id": "example-id",
      "event_type": "ssl.expiring",
      "detected_at": "2026-08-27T12:00:00Z",
      "published_at": "2026-08-27T12:00:00Z",
      "data": {}
    }
  ]
}
```

#### Codes de statut HTTP

- `200` OK
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## PATCH `/v1/watchlist/alerts/:subscription_id`

Opération: `updateWatchlistAlert`
Crédits et authentification: Gratuit
Authentification requise

PATCH /v1/watchlist/alerts/:subscription_id Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| subscription_id | string | requis |

#### Paramètres du corps

| Paramètre | Type | requis |
| --- | --- | --- |
| enabled | boolean | optionnel |
| events | string[] Valeurs autorisées `ssl.expiring`, `ssl.expired`, `ssl.changed`, `price.dropped`, `dns.changed`, `typosquat.detected`, `brand.updated` | optionnel |
| ssl_expiring_days | integer Valeurs autorisées `30`, `14`, `7`, `1` | optionnel |
| drop_percent | number \| null | optionnel |
| target_price | number \| null | optionnel |
| record_types | string[] Valeurs autorisées `A`, `AAAA`, `MX`, `NS`, `TXT`, `CNAME` | optionnel |
| attributes | string[] Valeurs autorisées `logo`, `wide_logo`, `colors`, `name`, `socials` | optionnel |
| notify_email | string \| null | optionnel |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `subscription` | object |
| `subscription.id` | string |
| `subscription.type` | string |
| `subscription.target` | string |
| `subscription.registrar` | string \| null |
| `subscription.events[]` | string[] |
| `subscription.status` | string |
| `subscription.ssl_expiring_days` | integer \| null |
| `subscription.price_type` | string \| null |
| `subscription.drop_percent` | number \| null |
| `subscription.target_price` | number \| null |
| `subscription.currency` | string \| null |
| `subscription.record_types[]` | string[] |
| `subscription.attributes[]` | string[] |
| `subscription.notify_email` | string \| null |
| `subscription.observed` | object \| null |
| `subscription.last_check_at` | string \| null |
| `subscription.last_check_status` | string \| null |
| `subscription.last_error` | string \| null |
| `subscription.next_check_at` | string \| null |
| `subscription.created_at` | string |
| `subscription.updated_at` | string |

#### Exemple de requête

```bash
curl -X PATCH "https://domscan.net/v1/watchlist/alerts/string" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "enabled": true,
  "events": [
    "ssl.expiring",
    "ssl.expired",
    "ssl.changed"
  ]
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/alerts/string", {
  method: "PATCH",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "enabled": true,
    "events": [
      "ssl.expiring",
      "ssl.expired",
      "ssl.changed"
    ]
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.patch(
    "https://domscan.net/v1/watchlist/alerts/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "enabled": True,
        "events": [
            "ssl.expiring",
            "ssl.expired",
            "ssl.changed",
        ],
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "enabled": true,
	  "events": [
	    "ssl.expiring",
	    "ssl.expired",
	    "ssl.changed"
	  ]
	}`)
	req, err := http.NewRequest(http.MethodPatch, "https://domscan.net/v1/watchlist/alerts/string", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/alerts/string")
request = Net::HTTP::Patch.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "enabled" => true,
  "events" => [
    "ssl.expiring",
    "ssl.expired",
    "ssl.changed"
  ]
})

#### Exemple de réponse

```json
{
  "subscription": {
    "id": "example-id",
    "type": "ssl",
    "target": "example",
    "registrar": "example",
    "events": [
      "ssl.expiring"
    ],
    "status": "active",
    "ssl_expiring_days": 30,
    "price_type": "registration",
    "drop_percent": 0.5,
    "target_price": 0.5,
    "currency": "USD",
    "record_types": [
      "A"
    ],
    "attributes": [
      "logo"
    ],
    "notify_email": "user@example.com",
    "observed": {},
    "last_check_at": "2026-08-27T12:00:00Z",
    "last_check_status": "baseline",
    "last_error": "example",
    "next_check_at": "2026-08-27T12:00:00Z",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z"
  }
}
```

#### Codes de statut HTTP

- `200` OK
- `400` Requête incorrecte
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## DELETE `/v1/watchlist/alerts/:subscription_id`

Opération: `deleteWatchlistAlert`
Crédits et authentification: Gratuit
Authentification requise

DELETE /v1/watchlist/alerts/:subscription_id Crédits: 0

#### Paramètres de requête

| Paramètre | Type | requis |
| --- | --- | --- |
| subscription_id | string | requis |

#### Champs de réponse

| Champ | Type |
| --- | --- |
| `id` | string |
| `deleted` | boolean |

#### Exemple de requête

```bash
curl -X DELETE "https://domscan.net/v1/watchlist/alerts/string" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'
```

```javascript
const response = await fetch("https://domscan.net/v1/watchlist/alerts/string", {
  method: "DELETE",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.delete(
    "https://domscan.net/v1/watchlist/alerts/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={},
)
print(response.json())
```

```go
package main

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

func main() {
	body := strings.NewReader(`{}`)
	req, err := http.NewRequest(http.MethodDelete, "https://domscan.net/v1/watchlist/alerts/string", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Status, string(data))
}
```

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/watchlist/alerts/string")
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.pretty_generate(JSON.parse(response.body))
```

#### Exemple de réponse

```json
{
  "id": "example-id",
  "deleted": true
}
```

#### Codes de statut HTTP

- `200` OK
- `401` Non autorisé
- `404` Introuvable
- `429` Trop de requêtes

## Ressources de référence

[OpenAPI 3.0](https://domscan.net/v1/openapi.json)
[Postman](https://domscan.net/v1/postman.json)
[MCP](https://domscan.net/fr/mcp-domain-checker)
