Dokumentacja dla deweloperów

Lista obserwacyjna domen

DomScan API do analizy domen: Monitoruj domeny pod kątem zmian wygaśnięcia i dostępności. Otrzymuj alerty, gdy zarejestrowane domeny stają się dostępne.

Lista obserwacyjna domen

Monitoruj domeny pod kątem zmian wygaśnięcia i dostępności. Otrzymuj alerty, gdy zarejestrowane domeny stają się dostępne.

Liczba domen, które możesz obserwować, zależy od Twojego planu. Konta bezpłatne mogą obserwować 5 domen. Konta płatne mogą obserwować jedną domenę na każde 30 kredytów miesięcznego planu, co wystarcza na codzienne sprawdzanie każdej domeny, co najmniej 100 i najwyżej 1000. Konta płatne bez planu miesięcznego mogą obserwować 100 domen. GET /v1/watchlist zwraca Twój bieżący limit jako max_domains. Dodanie ponad limit, duplikat lub nieprawidłowe dane są odrzucane i nie kosztują kredytów.

Monitoring

Zaloguj się przez Google, aby uzyskać dostęp do spersonalizowanej listy obserwowanych domen, alertów e-mail, webhooków i innych funkcji.

Otrzymuj powiadomienia przez e-mail, Telegram, Slack, Discord lub Webhook.

GET /v1/watchlist

Pobierz wszystkie domeny na liście obserwacyjnej.

Z paginacją: wyślij limit (od 1 do 100) i przekaż next_cursor z powrotem jako cursor. Odpowiedzi zawierają has_more i next_cursor. Bez limit zwracana jest cała lista. Zobacz paginację.

Przykładowa odpowiedź

{
                "watchlist": [
                {
                "domain": "startup.com",
                "added_at": "2024-01-15T10:30:00Z",
                "status": "registered",
                "expiry_date": "2025-01-15T00:00:00Z",
                "days_until_expiry": 287,
                "last_checked": "2024-03-01T12:00:00Z",
                "notify_email": "[email protected]",
                "check_count": 4
                }
                ],
                "total": 1,
                "max_domains": 333,
                "limit_basis": "monthly_credits",
                "updated_at": "2024-03-01T12:00:00Z"
                }

Pola odpowiedzi

Pole Typ
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
POST /v1/watchlist

Dodaj domenę do listy obserwacyjnej.

Treść żądania

{
                "domain": "mydomain.com",
                "notify_email": "[email protected]"
                }

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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": "[email protected]"
    },
    {
      "domain": "example.org",
      "added_at": "2026-10-09T10:15:30.000Z",
      "status": "unknown",
      "notify_email": "[email protected]"
    }
  ],
  "total": 2,
  "max_domains": 333,
  "limit_basis": "monthly_credits"
}
PATCH /v1/watchlist/:domain

Zmień adres e-mail alertów domeny, która jest już na Twojej liście obserwowanych, bez usuwania jej i dodawania od nowa. Wyślij notify_email jako null, aby go wyczyścić; alerty dla tej domeny trafią wtedy na adres powiadomień Twojego konta. Aktualizacje są bezpłatne.

Treść żądania

{
                "notify_email": "[email protected]"
                }
curl -X PATCH -H "X-API-Key: your-api-key" -H "Content-Type: application/json"                 -d '{"notify_email":"[email protected]"}' "https://domscan.net/v1/watchlist/mydomain.com"

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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": "[email protected]",
    "check_count": 12
  }
}
DELETE /v1/watchlist?domain=mydomain.com

Usuń z listy obserwowanych

curl -X DELETE -H "X-API-Key: your-api-key" "https://domscan.net/v1/watchlist?domain=mydomain.com"

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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": "[email protected]",
      "check_count": 1
    }
  ],
  "total": 1
}
GET /v1/watchlist/expiring?days=30

Wkrótce wygasające

Z paginacją: wyślij limit (od 1 do 100) i przekaż next_cursor z powrotem jako cursor. Odpowiedzi zawierają has_more i next_cursor. Bez limit zwracana jest cała lista. Zobacz paginację.

Przykładowa odpowiedź

{
                "expiring_domains": [
                {
                "domain": "renewal-window.com",
                "status": "expiring_soon",
                "expiry_date": "2026-05-12T00:00:00Z",
                "days_until_expiry": 28,
                "check_count": 11
                }
                ],
                "total": 1,
                "threshold_days": 30
                }

Pola odpowiedzi

Pole Typ
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
GET /v1/watchlist/available

Dostępna

Z paginacją: wyślij limit (od 1 do 100) i przekaż next_cursor z powrotem jako cursor. Odpowiedzi zawierają has_more i next_cursor. Bez limit zwracana jest cała lista. Zobacz paginację.

Przykładowa odpowiedź

{
                "available_domains": [
                {
                "domain": "startupdrop.ai",
                "status": "available",
                "last_checked": "2026-04-14T08:30:00Z",
                "check_count": 18
                }
                ],
                "total": 1,
                "message": "Te domeny z Twojej listy obserwowanych są teraz dostępne do rejestracji!"
                }

Pola odpowiedzi

Pole Typ
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

Webhooki alertów

Otrzymuj alerty monitorowania jako podpisane żądania POST z JSON-em na własne endpointy HTTPS. Zarządzaj endpointami za pomocą klucza API lub, po zalogowaniu, w ustawieniach Monitora.

Typy zdarzeń

MonitorZdarzenia
Dostępność, wygaśnięcie i status z listy obserwowanychdomain.available domain.expiring_30 domain.expiring_14 domain.expiring_7 domain.expiring_1 domain.status_change
Monitorowanie zmian domendomain.dns_changed domain.certificate_changed domain.registration_changed domain.hosting_changed domain.technology_changed domain.email_security_changed
Monitorowanie marki (nowe rejestracje podobnych domen)brand.threat_detected
Subskrypcje alertów listy obserwowanych (certyfikaty, ceny, rekordy DNS, domeny podobne)ssl.expiring ssl.expired ssl.changed price.dropped dns.changed typosquat.detected
Alerty o zmianach marki (logo, kolory, nazwa, profile społecznościowe)brand.updated
Zadania asynchroniczne (bezpłatne, tylko dla zadań utworzonych z notify_webhook)job.completed job.failed job.cancelled
Zdarzenie testowe (bezpłatne)webhook.test

Przeczytaj przewodnik po API alertów webhook

Cennik

Każdy alert dostarczony do endpointu z odpowiedzią 2xx kosztuje 2 kredytów. Kredyty są rezerwowane tuż przed pierwszą próbą i zwracane, jeśli dostarczenie się nie powiedzie, zostanie anulowane lub endpoint zostanie usunięty. Zdarzenia testowe są bezpłatne. Gdy saldo jest zbyt niskie, alert jest pomijany i nic nie jest pobierane.

POST /v1/webhooks

Zarejestruj endpoint HTTPS. Adres URL musi wskazywać na publiczny adres. Pomiń events lub przekaż ["*"], aby otrzymywać każdy typ zdarzenia. Sekret podpisu jest zwracany tylko w tej odpowiedzi.

Przykładowe żądanie

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

Przykładowa odpowiedź

{
  "endpoint": {
    "id": "whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3",
    "url": "https://hooks.example.com/domscan",
    "events": ["domain.available", "domain.expiring_30", "domain.dns_changed"],
    "status": "active",
    "secret_hint": "9c2e"
  },
  "secret": "whsec_..."
}

Pola odpowiedzi

Pole Typ
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
GET /v1/webhooks

Wyświetla Twoje endpointy wraz ze statusem, subskrybowanymi zdarzeniami, liczbą błędów i czterema ostatnimi znakami sekretu, a także dostępne typy zdarzeń i zasady dostarczania.

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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"
}
PATCH /v1/webhooks/:webhook_id

Wstrzymaj lub włącz endpoint, zmień jego zdarzenia albo edytuj opis. Włączenie endpointu zeruje licznik błędów.

{ "enabled": true, "events": ["*"] }

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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"
  }
}
DELETE /v1/webhooks/:webhook_id

Usuwa endpoint. Oczekujące dostarczenia są anulowane, a zarezerwowane kredyty zwracane.

Pola odpowiedzi

Pole Typ
id string
deleted boolean

Przykładowa odpowiedź

{
  "id": "example-id",
  "deleted": true
}
POST /v1/webhooks/:webhook_id/test

Wysyła jedno bezpłatne zdarzenie webhook.test i zwraca wynik. Zdarzenia testowe nie są ponawiane i nie wliczają się do automatycznego wstrzymania.

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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
}
POST /v1/webhooks/:webhook_id/rotate-secret

Zastępuje sekret podpisu endpointu, także wstrzymanego. Nowy sekret jest zwracany tylko w tej odpowiedzi. Przez kolejne 24 godziny każde dostarczenie jest podpisywane zarówno nowym, jak i poprzednim sekretem. Rotacja jest bezpłatna.

Przykładowe żądanie

curl -X POST "https://domscan.net/v1/webhooks/whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3/rotate-secret" \
  -H "X-API-Key: $DOMSCAN_API_KEY"

Przykładowa odpowiedź

{
  "endpoint": {
    "id": "whe_3f1c0a9b8e7d6c5b4a39281706f5e4d3",
    "status": "active",
    "secret_hint": "4b7a",
    "previous_secret_expires_at": "2026-10-11T12:00:00.000Z"
  },
  "secret": "whsec_...",
  "previous_secret_expires_at": "2026-10-11T12:00:00.000Z",
  "grace_period_seconds": 86400
}

Pola odpowiedzi

Pole Typ
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
GET /v1/webhooks/:webhook_id/deliveries

Parametry zapytania

ParametrTypOpis
limit integer Liczba dostarczeń do zwrócenia, od 1 do 100. Domyślnie 50.

Wyświetla ostatnie dostarczenia ze statusem, próbami, odpowiedzią HTTP, pobranymi kredytami i zwrotami. Rekordy dostarczeń są przechowywane przez 30 dni.

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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"
    }
  ]
}

Format żądania

Każdy alert to żądanie POST z treścią JSON. Pole id pozostaje takie samo dla danego zdarzenia i jest powtórzone w X-DomScan-Event-Id, dzięki czemu możesz ignorować ponowienia, które już przetworzono.

POST /domscan HTTP/1.1
Content-Type: application/json
X-DomScan-Event: domain.expiring_30
X-DomScan-Event-Id: evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9
X-DomScan-Timestamp: 1791633600
X-DomScan-Signature: sha256=...

{
  "id": "evt_6f1d2c3b4a5948e7b6c5d4e3f2a1b0c9",
  "type": "domain.expiring_30",
  "created": "2026-10-10T12:00:00.000Z",
  "data": {
    "domain": "acme.io",
    "previous_status": "registered",
    "current_status": "expiring_soon",
    "expiry_date": "2026-11-09T00:00:00Z",
    "days_until_expiry": 30,
    "checked_at": "2026-10-10T12:00:00.000Z"
  }
}

Weryfikacja podpisów

Oblicz HMAC-SHA256 z wartości X-DomScan-Timestamp, kropki i surowej treści żądania, używając sekretu swojego endpointu. Porównaj wynik z X-DomScan-Signature w stałym czasie i odrzucaj żądania ze znacznikiem czasu starszym niż 5 min.

Poniższy przykład sprawdza każdy podpis w nagłówku, więc działa także podczas rotacji sekretu.

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before JSON parsing.
function verifyDomScanWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-domscan-timestamp'];
  const header = headers['x-domscan-signature'] || '';
  if (!/^\d{10}$/.test(timestamp || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = Buffer.from('sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex'));
  // One entry normally; two during a secret rotation (new secret first).
  return header.split(',').some((entry) => {
    const candidate = Buffer.from(entry.trim());
    return candidate.length === expected.length &&
      crypto.timingSafeEqual(candidate, expected);
  });
}

Zmiana sekretu podpisu

W 24-godzinnym okresie przejściowym po rotacji nagłówek X-DomScan-Signature zawiera dwa podpisy oddzielone przecinkiem, z nowym sekretem na pierwszym miejscu, jak pokazano poniżej. Przyjmij żądanie, gdy którykolwiek wpis pasuje do sekretu, któremu ufasz, wdróż nowy sekret, a potem przestań ufać staremu. Ponowna rotacja w okresie przejściowym natychmiast unieważnia starszy poprzedni sekret.

X-DomScan-Signature: sha256=<new>,sha256=<previous>

Ponowienia i automatyczne wstrzymanie

Zwróć dowolny status 2xx w ciągu 8 sekund, aby potwierdzić alert. Przekierowania, inne kody statusu i przekroczenia czasu są ponawiane z wykładniczym opóźnieniem (1, 4, 16, 64 i 256 minut), łącznie do 6 prób. Po 15 kolejnych nieudanych próbach endpoint zostaje wstrzymany; włącz go ponownie przez PATCH lub w ustawieniach Monitora.

Gdy endpoint zostanie wstrzymany po powtarzających się błędach, jego właściciel otrzymuje jeden e-mail z hostem endpointu, ostatnim błędem i linkiem do ustawień Monitoringu. Napraw endpoint, a następnie włącz go ponownie w ustawieniach Monitoringu lub przez PATCH z enabled ustawionym na true. Włączenie zeruje licznik błędów.

Subskrypcje alertów listy obserwowanych

Zasubskrybuj dla obserwowanego elementu alerty, które chcesz otrzymywać. Każda subskrypcja obserwuje jedną nazwę hosta, TLD lub domenę marki, a Ty wybierasz, które z jej zdarzeń otrzymujesz. Zdarzenia trafiają do Twoich podpisanych punktów końcowych webhook oraz do alertów w aplikacji.

TypZdarzeniaKiedy się uruchamia
sslssl.expiring ssl.expired ssl.changedssl.expiring, gdy certyfikat używany przez nazwę hosta wygasa w ciągu ssl_expiring_days (30, 14, 7 lub 1, domyślnie 14), raz na certyfikat i próg. ssl.expired raz na każdy wygasły certyfikat. ssl.changed, gdy nowy odcisk certyfikatu zostanie zauważony w dwóch kolejnych kontrolach; ładunek informuje, czy zmienił się wystawca.
priceprice.droppedGdy cena rejestracji lub odnowienia TLD, u jednego rejestratora lub u najtańszego, spadnie o co najmniej drop_percent względem najwyższej ceny od ostatniego alertu albo osiągnie target_price lub mniej. Ceny pochodzą z dziennej migawki cen, a każda migawka jest oceniana raz.
dnsdns.changedGdy obserwowany typ rekordu (A, AAAA, MX, NS, TXT lub CNAME) dowolnej nazwy hosta zwraca tę samą nową odpowiedź w dwóch kolejnych potwierdzonych zapytaniach.
typosquattyposquat.detectedGdy nowo zarejestrowano domenę podobną do domeny marki, co potwierdza autorytatywne sprawdzenie rejestracji. Pierwszy pełny przebieg po domenach podobnych ustala stan bazowy i nie wysyła alertu.
brandbrand.updatedGdy kwadratowe logo, szerokie logo, kolory, nazwa lub zadeklarowane profile społecznościowe domeny marki ulegną zmianie, a zmiana zostanie zobaczona ponownie przy następnej kontroli. Wybierz, które z nich, za pomocą attributes (logo, wide_logo, colors, name, socials; domyślnie wszystkie). Pierwsza kontrola ustala stan wyjściowy i nie wysyła alertu, a atrybut, którego nie udało się sprawdzić, pozostaje bez zmian.

Zdarzenie wyzwalają tylko dokładne dowody. Nieudany handshake TLS, zapytanie DNS, które się nie powiodło lub przekroczyło limit czasu, brak ceny oraz zapytanie zablokowane lub ograniczone limitem mają status nieznany: nic nie zmieniają i nigdy nie powodują alertu ani opłaty. Pierwsza potwierdzona kontrola subskrypcji ustala jej stan bazowy.

Kontrole działają automatycznie: certyfikaty co 12 godzin, rekordy DNS co godzinę (z kontrolą potwierdzającą 15 minut po pierwszym zauważeniu zmiany), ceny co 2 godziny względem dziennej migawki, a domeny podobne w partiach po 30 z pełnym przebiegiem każdego dnia. Po kontroli o nieznanym wyniku kolejna próba następuje wcześniej. Subskrypcje marek są sprawdzane raz dziennie, z kontrolą potwierdzającą 90 minut po pierwszym wykryciu zmiany.

Tworzenie subskrypcji i wykonywanie kontroli jest bezpłatne. Każdy alert dostarczony do punktu końcowego webhook z odpowiedzią 2xx kosztuje 2 kredytów, tak jak każdy inny alert monitorowania. Nieudane dostarczenia są zwracane, a konto może mieć do 100 subskrypcji, w tym 20 dla domen podobnych.

POST /v1/watchlist/alerts

Utwórz subskrypcję. type decyduje o tym, które pola obowiązują: domain dla ssl, dns i typosquat; tld, registrar, price_type, drop_percent i target_price dla price. Pola, które nie dotyczą danego typu, są odrzucane.

Treść żądania

ParametrTypOpis
typestringssl, price, dns lub typosquat. Wymagane.
domainstringNazwa hosta do obserwowania dla ssl i dns albo domena marki dla typosquat.
tldstringTLD do obserwowania dla price, na przykład com.
registrarstringIdentyfikator rejestratora dla price. Pomiń, aby obserwować najtańszego rejestratora.
eventsstring[]Zdarzenia do otrzymywania. Domyślnie wszystkie zdarzenia danego typu.
ssl_expiring_daysintegerLiczba dni przed wygaśnięciem dla ssl.expiring: 30, 14, 7 lub 1. Domyślnie 14.
price_typestringregistration (domyślnie) lub renewal.
drop_percentnumberPowiadom o spadku o co najmniej tyle procent, od 1 do 95.
target_pricenumberPowiadom, gdy cena w USD osiągnie tę kwotę lub mniej. Subskrypcja cenowa wymaga drop_percent, target_price lub obu.
record_typesstring[]Typy rekordów do obserwowania dla dns. Domyślnie A, AAAA, MX, NS, TXT i CNAME.
notify_emailstringOpcjonalne. Wysyła też każdy alert tej subskrypcji e-mailem na ten adres (3 kredyty za każdy wysłany e-mail). Dostarczanie przez webhook się nie zmienia. Zmień go później przez PATCH albo wyślij null, aby zatrzymać e-maile.

Przykładowe żądanie

curl -X POST "https://domscan.net/v1/watchlist/alerts" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "price",
    "tld": "com",
    "registrar": "porkbun",
    "price_type": "renewal",
    "drop_percent": 10,
    "target_price": 9.5
  }'

Przykładowa odpowiedź

{
  "subscription": {
    "id": "mas_8c1f0e2d3b4a59687766554433221100",
    "type": "price",
    "target": "com",
    "registrar": "porkbun",
    "events": ["price.dropped"],
    "status": "active",
    "price_type": "renewal",
    "drop_percent": 10,
    "target_price": 9.5,
    "currency": "USD",
    "observed": null,
    "last_check_status": null,
    "next_check_at": "2026-10-10T12:00:00.000Z"
  }
}

Pola odpowiedzi

Pole Typ
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
GET /v1/watchlist/alerts

Wyświetl swoje subskrypcje wraz z ostatnimi potwierdzonymi dowodami i stanem kontroli, zdarzeniami obsługiwanymi przez każdy typ, harmonogramem kontroli i ceną alertu.

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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": "[email protected]",
      "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": {}
  }
}
GET /v1/watchlist/alerts/:subscription_id

Pobierz jedną subskrypcję wraz z ostatnimi potwierdzonymi dowodami i 20 najnowszymi zdarzeniami.

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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": "[email protected]",
    "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": {}
    }
  ]
}
PATCH /v1/watchlist/alerts/:subscription_id

Wstrzymaj lub wznów subskrypcję za pomocą enabled albo zmień events, ssl_expiring_days, drop_percent, target_price lub record_types. Nowa cena docelowa wywoła alert dopiero przy późniejszej zmianie ceny.

{ "enabled": false }
{ "notify_email": "[email protected]" }

Pola odpowiedzi

Pole Typ
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

Przykładowa odpowiedź

{
  "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": "[email protected]",
    "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"
  }
}
DELETE /v1/watchlist/alerts/:subscription_id

Usuń subskrypcję. Zdarzenia, które jeszcze nie zostały wysłane, są odrzucane i nigdy nie są rozliczane.

Pola odpowiedzi

Pole Typ
id string
deleted boolean

Przykładowa odpowiedź

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

Przykładowe zdarzenie dns.changed

{
  "id": "evt_2b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e",
  "type": "dns.changed",
  "created": "2026-10-10T12:15:00.000Z",
  "data": {
    "domain": "partner-shop.example",
    "changes": [
      {
        "record_type": "MX",
        "before": ["10 mx1.mail.example"],
        "after": ["10 mx.other-mail.example"],
        "added": ["10 mx.other-mail.example"],
        "removed": ["10 mx1.mail.example"],
        "first_seen_at": "2026-10-10T12:00:00.000Z"
      }
    ],
    "confirmed_checks": 2,
    "confirmed_at": "2026-10-10T12:15:00.000Z",
    "subscription_id": "mas_8c1f0e2d3b4a59687766554433221100"
  }
}