Domains API

Everything you can do on the dashboard, you can do over the API. Base URL:https://dominder.co/api/v1

The domain object

{
  "id":                  "66a1c0ffeec0ffee12345678",  // 24-char MongoDB ObjectId
  "hostname":            "example.com",
  "monitor": {
    "status":  true,    // HTTP(S) reachability
    "ssl":     true,    // TLS certificate health
    "records": true     // DNS record verification (requires `records`)
  },
  "records": [
    {
      "id":       "66a1...",
      "type":     "A",          // A | AAAA | CNAME | MX | TXT | NS
      "host":     "",           // "" means apex, otherwise the subdomain
      "expected": "93.184.216.34"
    }
  ],
  "intervalMinutes":     null,  // null = server default (usually 5)
  "paused":              false, // when true, scheduler skips this domain
  "lastStatus":          "ok",  // unknown | ok | warning | failing
  "lastCheckedAt":       "2026-04-22T12:34:56.000Z",
  "lastFailureAt":       null,
  "consecutiveFailures": 0,
  "createdAt":           "2026-04-20T09:00:00.000Z",
  "updatedAt":           "2026-04-22T12:34:56.000Z"
}

Field meanings:
hostname - just the bare hostname, nohttps://, no path, no port.
monitor - which checks to run. Toggles are independent; set only the ones you care about.
records - only used whenmonitor.recordsis true. SeeMonitoring checksfor the matching rules.
intervalMinutes - 1 to 1440 (24 h). Leave null to inherit the server default.
lastStatus - aggregate result of the most recent check run.

GET /me

Return the account this API key belongs to.

curl https://dominder.co/api/v1/me \
  -H "Authorization: Bearer $DOMINDER_API_KEY"

{
  "email":              "you@example.com",
  "name":               "Your Name",
  "tenantId":           "66a1c0ffeec0ffee12345678",
  "webhookUrl":         "https://your-app.example.com/dominder-webhook",
  "subscriptionStatus": "active"
}

GET /domains

Return every domain on your account, sorted by hostname.

curl https://dominder.co/api/v1/domains \
  -H "Authorization: Bearer $DOMINDER_API_KEY"

{
  "domains": [
    { "id": "66a1...", "hostname": "example.com",     "lastStatus": "ok",      ... },
    { "id": "66a2...", "hostname": "other.example.com", "lastStatus": "failing", ... }
  ]
}

POST /domains

Start monitoring a new domain. Request body:

curl -X POST https://dominder.co/api/v1/domains \
  -H "Authorization: Bearer $DOMINDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "example.com",
    "monitor":  { "status": true, "ssl": true, "records": true },
    "intervalMinutes": 5,
    "records":  [
      { "type": "A",     "host": "",    "expected": "93.184.216.34" },
      { "type": "CNAME", "host": "www", "expected": "example.com"   }
    ]
  }'

Successful response (HTTP 201):

{ "domain": { "id": "66a1...", ... } }

Common errors:

• 400 - invalid hostname or record definition (seeerrors)
• 409 - that hostname is already on your account
• 402 - subscription inactive

GET /domains/:id

Fetch a single domain.

curl https://dominder.co/api/v1/domains/66a1c0ffeec0ffee12345678 \
  -H "Authorization: Bearer $DOMINDER_API_KEY"

Response is a single{ "domain": {...} }object. Returns404if the id doesn't exist on your account.

GET /domains/:id/checks

Return historical check runs for one domain. Results are newest-first and default to the retained history window (45 days unless configured differently by your server).

curl "https://dominder.co/api/v1/domains/66a1c0ffeec0ffee12345678/checks?from=2026-03-01T00:00:00.000Z&to=2026-04-15T00:00:00.000Z&limit=3" \
  -H "Authorization: Bearer $DOMINDER_API_KEY"

{
  "checks": [
    {
      "id": "66b1...",
      "runAt": "2026-04-14T23:55:00.000Z",
      "status": "ok",
      "results": [
        { "kind": "status", "ok": true, "message": "HTTPS 200", "details": { ... } },
        { "kind": "ssl", "ok": true, "message": "Valid - expires in 42 day(s).", "details": { ... } }
      ],
      "createdAt": "2026-04-14T23:55:00.010Z",
      "updatedAt": "2026-04-14T23:55:00.010Z"
    }
  ],
  "meta": {
    "domainId": "66a1c0ffeec0ffee12345678",
    "from": "2026-03-01T00:00:00.000Z",
    "to": "2026-04-15T00:00:00.000Z",
    "limit": 3,
    "nextCursor": "2026-04-14T23:55:00.000Z|66b1...",
    "retentionDays": 45
  }
}

If more rows exist,meta.nextCursoris returned. Pass it back asbeforeto page backward in time.

PATCH /domains/:id

Partially update a domain. Only the fields you include are changed. All top-level fields fromPOST /domainsare accepted, plus:

• paused - whentrue, the scheduler skips this domain until you flip it back tofalse. Records and settings are kept intact.

curl -X PATCH https://dominder.co/api/v1/domains/66a1c0ffeec0ffee12345678 \
  -H "Authorization: Bearer $DOMINDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paused": true, "intervalMinutes": 15 }'

Sendingrecordsreplaces the whole array - to append, fetch, append, then PATCH back.

DELETE /domains/:id

Stop monitoring and delete the domain. Historical check results are also removed.

curl -X DELETE https://dominder.co/api/v1/domains/66a1c0ffeec0ffee12345678 \
  -H "Authorization: Bearer $DOMINDER_API_KEY"

{ "ok": true }

Pagination, filtering, and search

Domain listing pagination is not yet supported. GET /domainsstill returns all domains in one call, sorted by hostname. For check history, useGET /domains/:id/checkswithbeforeandlimit.