Domains API

Manage monitored domains programmatically.

List Domains

GET /api/domains

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "orgId": "660e8400-e29b-41d4-a716-446655440000",
      "domain": "competitor.com",
      "displayName": "Competitor",
      "status": "active",
      "checkFrequencyHours": 24,
      "lastCrawledAt": "2024-01-15T10:30:00Z",
      "nextCrawlAt": "2024-01-16T10:30:00Z",
      "pages": [
        {
          "id": "770e8400-e29b-41d4-a716-446655440000",
          "url": "https://competitor.com/pricing",
          "pageType": "pricing",
          "status": "active"
        }
      ],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

Get Domain

GET /api/domains/:id

Returns domain details including pages and recent changes.

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "660e8400-e29b-41d4-a716-446655440000",
    "domain": "competitor.com",
    "displayName": "Competitor",
    "status": "active",
    "checkFrequencyHours": 24,
    "lastCrawledAt": "2024-01-15T10:30:00Z",
    "nextCrawlAt": "2024-01-16T10:30:00Z",
    "pages": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "domainId": "550e8400-e29b-41d4-a716-446655440000",
        "url": "https://competitor.com/pricing",
        "pageType": "pricing",
        "status": "active",
        "monitoringEnabled": true,
        "lastCheckAt": "2024-01-15T10:30:00Z",
        "lastChangeAt": "2024-01-10T08:15:00Z"
      }
    ],
    "recentChanges": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440000",
        "pageId": "770e8400-e29b-41d4-a716-446655440000",
        "changeType": "price_change",
        "severity": "high",
        "summary": "Price increased from $99 to $129",
        "createdAt": "2024-01-10T08:15:00Z"
      }
    ],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Add Domain

POST /api/domains

Adding a domain automatically triggers page discovery. The response includes a discoveryJobId to track progress.

Request Body

Parameter	Type	Required	Description
domain	string	Yes	Domain to monitor (e.g., competitor.com)
displayName	string	No	Friendly name for the domain

{
  "domain": "competitor.com",
  "displayName": "Main Competitor"
}

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "660e8400-e29b-41d4-a716-446655440000",
    "domain": "competitor.com",
    "displayName": "Main Competitor",
    "status": "discovering",
    "checkFrequencyHours": 24,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "discoveryJobId": "12345"
  }
}

Tracking Discovery

Use the discoveryJobId with the Jobs API to check when discovery completes:

GET /api/jobs/12345

Delete Domain

DELETE /api/domains/:id

Deleting a domain removes all associated pages, snapshots, and changes.

Response

{
  "data": {
    "deleted": true,
    "message": "Domain competitor.com deleted"
  }
}

Trigger Discovery

POST /api/domains/:id/discover

Re-discover pages on an existing domain. Useful when a competitor adds new sections to their site.

Heavy Rate Limit

This endpoint has a heavy rate limit of 10 requests per hour. Use sparingly.

Response

{
  "data": {
    "domain": "competitor.com",
    "discoveryJobId": "12346",
    "message": "Discovery job queued"
  }
}

Trigger Crawl

POST /api/domains/:id/crawl

Immediately crawl all monitored pages for a domain. Normally, Diffy crawls pages on a schedule, but you can trigger an immediate crawl when needed.

Heavy Rate Limit

This endpoint has a heavy rate limit of 10 requests per hour. Use sparingly.

Response

{
  "data": {
    "domain": "competitor.com",
    "queued": 5,
    "jobIds": ["12347", "12348", "12349", "12350", "12351"],
    "message": "Queued 5 crawl jobs"
  }
}

If no pages are enabled for monitoring:

{
  "data": {
    "domain": "competitor.com",
    "queued": 0,
    "jobIds": [],
    "message": "No pages to crawl"
  }
}

Domain Status Values

Status	Description
discovering	Initial page discovery in progress
active	Domain is being monitored
paused	Monitoring paused (manual or billing)
error	Repeated crawl failures

Error Codes

Code	Status	Description
NOT_FOUND	404	Domain not found or not owned by your org
CONFLICT	409	Domain already exists for your organization