API Integration Guide

This page explains how to authenticate and integrate with the API to manage domain entries and their country rules.

Base URL: https://domainreach.io

Authentication

Authenticate using the X-API-Key header. Example:

X-API-Key: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Endpoints

Method	Endpoint	Description
GET	/api/integration/v1/domains	List all monitored domains (paginated).
POST	/api/integration/v1/save	Create or update a domain with country rules and category.
POST	/api/integration/v1/fetch	Get blocking status for specific domains.
PUT	/api/integration/v1/toggle/:domainName/:enabled	Enable or disable monitoring for a domain.
DELETE	/api/integration/v1/delete/:domainName	Remove a domain from monitoring.

GET/api/integration/v1/domains

JSON

List all monitored domains for your space. Results are paginated — max 100 domains per page.

Header	Value
X-API-Key	Your API key

Param	Type	Default	Description
page	integer	0	Page number (zero‑based).
size	integer	100	Items per page (max 100).

Response Body

{
  "page": 0,
  "totalPages": 3,
  "totalElements": 250,
  "lastPage": false,
  "domains": [
    {
      "name": "example.com",
      "created": "2026-03-27T14:43:37",
      "enabled": true,
      "countries": [
        "DE",
        "PT",
        "AU"
      ]
    },
    {
      "name": "test.org",
      "created": "2026-03-20T09:15:00",
      "enabled": false,
      "countries": [
        "TR"
      ]
    }
  ]
}

POST/api/integration/v1/save

JSON

Create or update a domain's country rules and category. Re‑using categories is automatic; new categories are created as needed until the limit is reached.

Header	Value
X-API-Key	Your API key
Content-Type	application/json

Request Body

{
  "domainName": "example.com",
  "countryCodes": [
    "DE",
    "PT",
    "AU"
  ],
  "category": "category"
}

domainName – string; required.
countryCodes – array of ISO alpha‑2 codes; invalid/non‑existing codes are ignored.
category – string; required. Reused if exists, otherwise created automatically.
Category creation limit: max 100 per space. If exceeded, request fails with 400 status code and {"message":"CATEGORIES_LIMIT"}.

POST/api/integration/v1/fetch

JSON

Fetch monitoring status for a list of domains. Returns each domain's monitored countries and whether it is blocked (with the date the block was detected).

Header	Value
X-API-Key	Your API key
Content-Type	application/json

Request Body

{
  "domains": [
    "example.com",
    "test.org"
  ]
}

domains – array of domain name strings; required. Domains not found in your space are silently omitted from the response.

Response Body

{
  "domains": [
    {
      "domainName": "example.com",
      "countries": [
        {
          "countryCode": "DE",
          "blocked": false,
          "blockedTime": null
        },
        {
          "countryCode": "PT",
          "blocked": true,
          "blockedTime": "2025-03-15T10:30:00"
        }
      ]
    },
    {
      "domainName": "test.org",
      "countries": [
        {
          "countryCode": "AU",
          "blocked": false,
          "blockedTime": null
        }
      ]
    }
  ]
}

DELETE/api/integration/v1/delete/:domainName

–

Remove a domain configuration.

Path params:

Param	Type	Required	Description
domainName	string	yes	Domain to remove.

PUT/api/integration/v1/toggle/:domainName/:enabled

–

Enable or disable monitoring for a domain.

Path params:

Param	Type	Required	Description
domainName	string	yes	Domain name to toggle.
enabled	boolean	yes	`true` to enable, `false` to disable.

Header	Value
X-API-Key	Your API key

Rate Limits

All API endpoints that require X-API-Key authentication are rate‑limited to 30 requests per minute per API key. The limit applies across all endpoints combined (save, fetch, delete).

Limit	Window	Scope
30 requests	1 minute (sliding window)	Per API key

If the limit is exceeded, the API responds with 429 Too Many Requests. Wait until the window resets before retrying.

Status & Error Reference

Case	Status	Body / Notes
API key is invalid	`401`	—
Wrong request type (e.g., should be GET but POST)	`401`	—
`POST` /v1/save success	`200`	{ "status": "OK" }
`GET` /v1/domains success	`200`	{ "page":0, "totalPages":…, "lastPage":…, "domains":[…] }
`POST` /v1/fetch success	`200`	{ "domains": [...] }
`PUT` /v1/toggle success	`200`	{ "status": "OK" }
`PUT` /v1/toggle non‑existing domain	`400`	{ "message": "NOT_FOUND" }
`DELETE` /v1/delete success	`200`	—
`DELETE` non‑existing domain	`400`	{ "message": "NOT_FOUND" }
Category limit exceeded (fallback)	`400`	{ "message": "CATEGORIES_LIMIT" }
Rate limit exceeded (30 req/min)	`429`	Rate limit exceeded

Invalid alpha‑2 country codes in countryCodes are silently ignored.

Implementation Notes

Use POST /api/integration/v1/save to create or update a domain's list of countryCodes and its category.
Deleting a domain is idempotent in terms of outcome message (NOT_FOUND when it doesn't exist).
All examples assume a API key in X-API-Key header.