Domains API

Manage domains — list, create, update, delete, retrieve health and security security status.

GET/api/v1/domainsAuth required

List all domains in your account. Supports filtering by domain name and portfolio.

Query Parameters

Parameter	Type	Required	Description
domain	string	No	Filter by domain name (partial match)
portfolio_id	string	No	Filter by portfolio UUID
limit	number	No	Max results per page, default 50
offset	number	No	Pagination offset, default 0

Response

json

{
  "domains": [
    {
      "id": "uuid",
      "domain": "example.com",
      "portfolio_id": "uuid",
      "is_verified": true,
      "health_score": 85,
      "health_grade": "B",
      "expiry_date": "2025-12-01",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET/api/v1/domains/:idAuth required

Get a single domain by its UUID, including full WHOIS data.

Query Parameters

Parameter	Type	Required	Description
include_endpoints	boolean	No	Include associated endpoints in the response

Response

json

{
  "id": "uuid",
  "domain": "example.com",
  "portfolio_id": "uuid",
  "is_verified": true,
  "health_score": 85,
  "health_grade": "B",
  "whois": {
    "registrar": "Namecheap",
    "expiry_date": "2025-12-01",
    "nameservers": ["ns1.example.com"]
  },
  "created_at": "2026-01-01T00:00:00Z"
}

POST/api/v1/domainsAuth required

Add a new domain to your account. Returns a verification token for DNS ownership verification.

Request Body

Parameter	Type	Required	Description
domain	string	Yes	Domain name, e.g. example.com
portfolio_id	string	No	Portfolio UUID to assign this domain to
notes	string	No	Optional free-text notes

Response

json

{
  "id": "uuid",
  "domain": "example.com",
  "portfolio_id": "uuid",
  "verification_token": "domainops-verify-xxxx",
  "is_verified": false,
  "created_at": "2026-01-01T00:00:00Z"
}

Error Codes

Status	Description
409	Domain already exists in your account
402	Domain limit reached for your plan

POST/api/v1/domains/bulkAuth required

Create multiple domains in a single request.

Request Body

Parameter	Type	Required	Description
operation	string	Yes	Must be 'create'
domains	array	Yes	Array of domain objects with the same fields as POST /domains

Response

json

{
  "message": "2 domains created",
  "domains": [
    { "id": "uuid", "domain": "example.com" },
    { "id": "uuid", "domain": "example.org" }
  ]
}

PUT/api/v1/domains/:idAuth required

Update a domain's name, portfolio assignment, or notes.

Request Body

Parameter	Type	Required	Description
domain	string	No	New domain name
portfolio_id	string	No	Reassign to a different portfolio
notes	string	No	Update notes

Response

json

{
  "id": "uuid",
  "domain": "example.com",
  "portfolio_id": "uuid",
  "notes": "Updated notes",
  "updated_at": "2026-03-28T09:00:00Z"
}

DELETE/api/v1/domains/:idAuth required

Delete a domain and all associated data including endpoints, liveness configs, and exposure results.

Response

json

{
  "message": "Domain deleted",
  "deleted_domain": {
    "id": "uuid",
    "domain": "example.com"
  }
}

GET/api/v1/domains/:id/verifyAuth required

Retrieve the DNS verification token for a domain. Add the token as a TXT record at _domainops-verify.<domain>; our worker picks up the change on its next cycle and flips is_verified to true automatically. Poll GET /api/v1/domains/:id to watch for the transition.

Response

json

{
  "id": "uuid",
  "domain": "example.com",
  "verification_token": "domainops-verify-xxxx",
  "is_verified": false
}

PATCH/api/v1/domains/:id/exposureAuth required

Enable or disable exposure scanning for a domain. The exposure-worker only scans domains with this flag set; scans run on the worker's own cadence. Domain must be verified before enabling.

Example request

json

{
  "enabled": true
}

Response

json

{
  "id": "uuid",
  "domain": "example.com",
  "is_verified": true,
  "exposure_monitoring_enabled": true
}

Error Codes

Status	Description
403	Domain must be verified before exposure scanning can be enabled.

GET/api/v1/domains/:id/statusAuth required

Get the current health status of a domain including WHOIS expiry and SSL summary.

Response

json

{
  "domain": "example.com",
  "is_verified": true,
  "health_score": 85,
  "health_grade": "B",
  "overall_status": "healthy",
  "whois": {
    "expiry_date": "2025-12-01",
    "days_until_expiry": 245
  },
  "ssl": {
    "status": "valid",
    "expiry_date": "2025-06-01"
  }
}

GET/api/v1/domains/:id/securityAuth required

Get security check results for a domain including SPF, DMARC, DKIM, CAA, DNSSEC, and transfer lock status.

Response

json

{
  "domain": "example.com",
  "transfer_lock": true,
  "dnssec_enabled": false,
  "security_score": 72,
  "checks": {
    "spf": "pass",
    "dmarc": "pass",
    "dkim": "fail",
    "caa": "pass"
  },
  "recommendations": [
    "Enable DNSSEC",
    "Add DKIM record"
  ]
}