Domains

Download schema

Domain registrations Spectate watches at their registry (RDAP or WHOIS): it alerts before a domain expires and, optionally, when its registrar, nameservers or DNSSEC keys change. The plan limits the number of domains.

List domains

GET

https://api.spectate.net/v1

/domains

Returns the team's monitored domains, newest first unless you sort.

List domains › query Parameters

page

integer

Page number, from 1.

Default: 1

per_page

integer

Domains per page, 1 to 100.

Default: 25

filter[view]

DomainView · enum

Only domains in this view.

Domain list views; a domain can be in several.


`attention` Expired, or expiring within its `expiry_threshold_days`.
`unsigned` No DNSSEC keys.
`paused` Monitoring is paused.

Enum values:

attention

unsigned

paused

filter[project_id]

string · uuid

Only domains of this project.

filter[search]

string

Case-insensitive text in the name, registrar or nameservers.

sort

string

Sort by name, expires_at (unknown expiry last) or created_at. Prefix - for descending. Default -created_at.

List domains › Responses

Paginated set of Domain

current_page

integer · min: 1 · required

Domain[] · required

first_page_url

string | null · required

from

integer | null · min: 1 · required

last_page_url

string | null · required

last_page

integer · min: 1 · required

object[] · required

Generated paginator links.

next_page_url

string | null · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

prev_page_url

string | null · required

to

integer | null · min: 1 · required

Number of the last item in the slice.

total

integer · min: 0 · required

Total number of items being paginated.

GET/domains

curl https://api.spectate.net/v1/domains \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "current_page": 1,
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "example.com",
      "enabled": true,
      "paused_reason": "plan_limit",
      "registrar": "Example Registrar, Inc.",
      "registered_at": "2024-08-25T15:00:00Z",
      "expires_at": "2024-08-25T15:00:00Z",
      "registry_changed_at": "2024-08-25T15:00:00Z",
      "days_until_expiration": 212,
      "is_expired": true,
      "is_expiring_soon": true,
      "nameservers": [
        "string"
      ],
      "dnssec": true,
      "dnssec_keys": [
        {
          "key_tag": 2371,
          "algorithm": 13,
          "digest_type": 2,
          "digest": "digest"
        }
      ],
      "statuses": [
        "string"
      ],
      "registry_source": "rdap",
      "registry_error": "unsupported",
      "last_checked_at": "2024-08-25T15:00:00Z",
      "expiry_threshold_days": 30,
      "alert_on_registry_changes": true,
      "project_id": "00000000-0000-0000-0000-000000000000",
      "escalation_paths": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "On-call engineers"
        }
      ],
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "first_page_url": "first_page_url",
  "from": 1,
  "last_page_url": "last_page_url",
  "last_page": 1,
  "links": [
    {
      "url": "url",
      "label": "label",
      "active": true
    }
  ],
  "next_page_url": "next_page_url",
  "path": "path",
  "per_page": 0,
  "prev_page_url": "prev_page_url",
  "to": 1,
  "total": 0
}

json

application/json

Add a domain

POST

https://api.spectate.net/v1

/domains

Starts monitoring it and looks it up at its registry right away; the registry fields fill in within a minute. Without project_id it joins the team's default project. The plan limits the number of domains (403 PLAN_LIMIT_REACHED).

Add a domain › Request Body

A domain to monitor.

CreateDomain

name

string · maxLength: 255 · required

The registered domain, without www. or a path; internationalised names may be in Unicode or punycode

Example: example.com

enabled

boolean

Whether to start monitoring at once. Default true

expiry_threshold_days

integer · min: 1 · max: 365

Days before expiry, 1 to 365, that the "expires soon" alert fires. Default 30

Example: 30

alert_on_registry_changes

boolean

Raise an alert when the registrar, nameservers or DNSSEC keys change. Default true

project_id

string | null · uuid

Project to add the domain to; default the team's default project, null for none

escalation_path_ids

string[]

Escalation paths for the domain's alerts. Leave out or send [] to follow the project's paths, else the team's default path

Add a domain › Responses

The new domain.

A monitored domain registration: Spectate looks it up at its registry (RDAP or WHOIS) every few hours and alerts before it expires and, optionally, when its registrar, nameservers or DNSSEC change.

Domain

id

string · uuid · required

Domain ID

name

string · required

The registered domain, lowercase, internationalised names in punycode

Example: example.com

enabled

boolean · required

Whether the domain is monitored. false when paused by a member or by the system (see paused_reason)

required

registrar

string | null · required

The registrar, as the registry reports it

Example: Example Registrar, Inc.

registered_at

string | null · date-time · required

When the domain was registered

expires_at

string | null · date-time · required

When the registration expires

registry_changed_at

string | null · date-time · required

When the registration last changed at the registry

days_until_expiration

integer | null · required

Days until the registration expires; negative once expired

Example: 212

is_expired

boolean · required

Whether the registration has expired

is_expiring_soon

boolean · required

Whether it expires within expiry_threshold_days

nameservers

array | null · required

The domain's nameservers

dnssec

boolean · required

Whether the registry publishes DNSSEC keys for the domain

array | null · required

The DNSSEC delegation signer records

statuses

array | null · required

EPP status codes, for example client transfer prohibited

required

last_checked_at

string | null · date-time · required

When the registry was last checked

expiry_threshold_days

integer · required

Days before expiry that the "expires soon" alert fires

Example: 30

alert_on_registry_changes

boolean · required

Whether changes of the registrar, nameservers or DNSSEC keys raise an alert

project_id

string | null · uuid · required

The project the domain belongs to; null for none

EscalationPathReference[] · required

Escalation paths the domain's alerts follow. Empty: the project's paths, else the team's default path

created_at

string · date-time · required

When monitoring of the domain started

POST/domains

curl https://api.spectate.net/v1/domains \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "example.com",
  "enabled": true,
  "expiry_threshold_days": 30,
  "alert_on_registry_changes": true,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

Example Request Body

{
  "name": "example.com",
  "enabled": true,
  "expiry_threshold_days": 30,
  "alert_on_registry_changes": true,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "example.com",
  "enabled": true,
  "paused_reason": "plan_limit",
  "registrar": "Example Registrar, Inc.",
  "registered_at": "2024-08-25T15:00:00Z",
  "expires_at": "2024-08-25T15:00:00Z",
  "registry_changed_at": "2024-08-25T15:00:00Z",
  "days_until_expiration": 212,
  "is_expired": true,
  "is_expiring_soon": true,
  "nameservers": [
    "string"
  ],
  "dnssec": true,
  "dnssec_keys": [
    {
      "key_tag": 2371,
      "algorithm": 13,
      "digest_type": 2,
      "digest": "digest"
    }
  ],
  "statuses": [
    "string"
  ],
  "registry_source": "rdap",
  "registry_error": "unsupported",
  "last_checked_at": "2024-08-25T15:00:00Z",
  "expiry_threshold_days": 30,
  "alert_on_registry_changes": true,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_paths": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call engineers"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Get a domain

GET

https://api.spectate.net/v1

/domains/{domain}

Returns the domain with what its registry reported at the last check.

Get a domain › path Parameters

domain

string · uuid · required

Domain ID.

Get a domain › Responses

The domain.

A monitored domain registration: Spectate looks it up at its registry (RDAP or WHOIS) every few hours and alerts before it expires and, optionally, when its registrar, nameservers or DNSSEC change.

Domain

id

string · uuid · required

Domain ID

name

string · required

The registered domain, lowercase, internationalised names in punycode

Example: example.com

enabled

boolean · required

Whether the domain is monitored. false when paused by a member or by the system (see paused_reason)

required

registrar

string | null · required

The registrar, as the registry reports it

Example: Example Registrar, Inc.

registered_at

string | null · date-time · required

When the domain was registered

expires_at

string | null · date-time · required

When the registration expires

registry_changed_at

string | null · date-time · required

When the registration last changed at the registry

days_until_expiration

integer | null · required

Days until the registration expires; negative once expired

Example: 212

is_expired

boolean · required

Whether the registration has expired

is_expiring_soon

boolean · required

Whether it expires within expiry_threshold_days

nameservers

array | null · required

The domain's nameservers

dnssec

boolean · required

Whether the registry publishes DNSSEC keys for the domain

array | null · required

The DNSSEC delegation signer records

statuses

array | null · required

EPP status codes, for example client transfer prohibited

required

last_checked_at

string | null · date-time · required

When the registry was last checked

expiry_threshold_days

integer · required

Days before expiry that the "expires soon" alert fires

Example: 30

alert_on_registry_changes

boolean · required

Whether changes of the registrar, nameservers or DNSSEC keys raise an alert

project_id

string | null · uuid · required

The project the domain belongs to; null for none

EscalationPathReference[] · required

Escalation paths the domain's alerts follow. Empty: the project's paths, else the team's default path

created_at

string · date-time · required

When monitoring of the domain started

GET/domains/{domain}

curl https://api.spectate.net/v1/domains/:domain \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "example.com",
  "enabled": true,
  "paused_reason": "plan_limit",
  "registrar": "Example Registrar, Inc.",
  "registered_at": "2024-08-25T15:00:00Z",
  "expires_at": "2024-08-25T15:00:00Z",
  "registry_changed_at": "2024-08-25T15:00:00Z",
  "days_until_expiration": 212,
  "is_expired": true,
  "is_expiring_soon": true,
  "nameservers": [
    "string"
  ],
  "dnssec": true,
  "dnssec_keys": [
    {
      "key_tag": 2371,
      "algorithm": 13,
      "digest_type": 2,
      "digest": "digest"
    }
  ],
  "statuses": [
    "string"
  ],
  "registry_source": "rdap",
  "registry_error": "unsupported",
  "last_checked_at": "2024-08-25T15:00:00Z",
  "expiry_threshold_days": 30,
  "alert_on_registry_changes": true,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_paths": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call engineers"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Update a domain

PATCH

https://api.spectate.net/v1

/domains/{domain}

Changes only the fields you send. A new name forgets the old registration data and is looked up at once. Resuming (enabled: true) goes through the plan's domain limit.

Update a domain › path Parameters

domain

string · uuid · required

Domain ID.

Update a domain › Request Body

Changes to a monitored domain; fields you leave out keep their value.

UpdateDomain

name

string · maxLength: 255

Another domain to monitor instead; its registry data is looked up again

Example: example.org

enabled

boolean

Pause (false) or resume (true) monitoring. Resuming goes through the plan's domain limit

expiry_threshold_days

integer · min: 1 · max: 365

Days before expiry, 1 to 365, that the "expires soon" alert fires

alert_on_registry_changes

boolean

Raise an alert when the registrar, nameservers or DNSSEC keys change

project_id

string | null · uuid

Project of the domain; null for none

escalation_path_ids

string[]

Escalation paths for the domain's alerts; replaces the current ones

Update a domain › Responses

The updated domain.

A monitored domain registration: Spectate looks it up at its registry (RDAP or WHOIS) every few hours and alerts before it expires and, optionally, when its registrar, nameservers or DNSSEC change.

Domain

id

string · uuid · required

Domain ID

name

string · required

The registered domain, lowercase, internationalised names in punycode

Example: example.com

enabled

boolean · required

Whether the domain is monitored. false when paused by a member or by the system (see paused_reason)

required

registrar

string | null · required

The registrar, as the registry reports it

Example: Example Registrar, Inc.

registered_at

string | null · date-time · required

When the domain was registered

expires_at

string | null · date-time · required

When the registration expires

registry_changed_at

string | null · date-time · required

When the registration last changed at the registry

days_until_expiration

integer | null · required

Days until the registration expires; negative once expired

Example: 212

is_expired

boolean · required

Whether the registration has expired

is_expiring_soon

boolean · required

Whether it expires within expiry_threshold_days

nameservers

array | null · required

The domain's nameservers

dnssec

boolean · required

Whether the registry publishes DNSSEC keys for the domain

array | null · required

The DNSSEC delegation signer records

statuses

array | null · required

EPP status codes, for example client transfer prohibited

required

last_checked_at

string | null · date-time · required

When the registry was last checked

expiry_threshold_days

integer · required

Days before expiry that the "expires soon" alert fires

Example: 30

alert_on_registry_changes

boolean · required

Whether changes of the registrar, nameservers or DNSSEC keys raise an alert

project_id

string | null · uuid · required

The project the domain belongs to; null for none

EscalationPathReference[] · required

Escalation paths the domain's alerts follow. Empty: the project's paths, else the team's default path

created_at

string · date-time · required

When monitoring of the domain started

PATCH/domains/{domain}

curl https://api.spectate.net/v1/domains/:domain \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "example.org",
  "enabled": true,
  "expiry_threshold_days": 1,
  "alert_on_registry_changes": true,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

Example Request Body

{
  "name": "example.org",
  "enabled": true,
  "expiry_threshold_days": 1,
  "alert_on_registry_changes": true,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_path_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "example.com",
  "enabled": true,
  "paused_reason": "plan_limit",
  "registrar": "Example Registrar, Inc.",
  "registered_at": "2024-08-25T15:00:00Z",
  "expires_at": "2024-08-25T15:00:00Z",
  "registry_changed_at": "2024-08-25T15:00:00Z",
  "days_until_expiration": 212,
  "is_expired": true,
  "is_expiring_soon": true,
  "nameservers": [
    "string"
  ],
  "dnssec": true,
  "dnssec_keys": [
    {
      "key_tag": 2371,
      "algorithm": 13,
      "digest_type": 2,
      "digest": "digest"
    }
  ],
  "statuses": [
    "string"
  ],
  "registry_source": "rdap",
  "registry_error": "unsupported",
  "last_checked_at": "2024-08-25T15:00:00Z",
  "expiry_threshold_days": 30,
  "alert_on_registry_changes": true,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "escalation_paths": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call engineers"
    }
  ],
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Delete a domain

DELETE

https://api.spectate.net/v1

/domains/{domain}

Monitoring stops and the domain no longer appears in the API or the dashboard. Seven days later the domain is deleted permanently with all its data, alerts included. Until then support can restore it on request. Nothing changes at the registrar. Deleting the same domain again returns 404.

Delete a domain › path Parameters

domain

string · uuid · required

Domain ID.

Delete a domain › Responses

No content

No data returned

Metric conditions Projects