API Overview

The Diffy API allows you to programmatically manage domains, monitor pages, and access detected changes.

Base URL

https://api.trydiffy.com

Authentication

All API requests require authentication via API key. See Authentication for details.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.trydiffy.com/api/domains

Response Format

All responses are JSON with a consistent envelope:

Success Response

{
  "data": { ... },
  "meta": {
    "total": 10,
    "page": 1,
    "pageSize": 20
  }
}

Error Response

{
  "error": "Domain not found",
  "code": "NOT_FOUND"
}

This is the format for all API errors including quota limits (402), validation (400), not found (404), and rate limit (429). Some errors include an additional details object with context-specific fields.

Note: Auth errors (401) from the authentication middleware use a nested format: { "error": { "code": "...", "message": "..." } }.

Status Codes

Code	Description
200	Success
201	Created
400	Bad request - Invalid parameters
401	Unauthorized - Invalid or missing API key
402	Payment required - Quota/limit exceeded
403	Forbidden - Insufficient permissions
404	Not found
409	Conflict - Resource already exists
429	Rate limited
500	Server error

For detailed error codes and handling, see Error Codes.

Rate Limits

Diffy uses tiered rate limits to balance access with resource-intensive operations.

Standard Rate Limit

Most endpoints: 100 requests per minute

• GET /api/domains
• POST /api/domains
• GET /api/domains/:id
• DELETE /api/domains/:id
• GET /api/domains/:id/pages
• POST /api/domains/:id/pages
• GET /api/jobs
• GET /api/jobs/:id
• GET /api/jobs/stats

Heavy Rate Limit

Resource-intensive operations: 10 requests per hour

• POST /api/domains/:id/discover
• POST /api/domains/:id/crawl

Rate Limit Headers

All responses include rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

When rate limited, responses include a Retry-After header with seconds to wait.

Request Tracing

Every request is assigned a unique trace ID for debugging and support.

Trace ID Header

X-Trace-Id: abc123-def456-ghi789

Include this ID when contacting support about specific requests. You can also pass your own trace ID in requests:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-Trace-Id: my-custom-trace-id" \
     https://api.trydiffy.com/api/domains

API Documentation

OpenAPI Specification

The full OpenAPI 3.1 specification is available for download:

https://api.trydiffy.com/openapi.json

Use this to generate client SDKs, import into Postman, or integrate with API tools.

Interactive Explorer

Try the API directly in your browser with Swagger UI:

https://api.trydiffy.com/swagger

Endpoints

Endpoint	Method	Rate Limit	Description
/api/domains	GET	Standard	List all domains
/api/domains	POST	Standard	Add a new domain
/api/domains/:id	GET	Standard	Get domain details + changes
/api/domains/:id	DELETE	Standard	Delete a domain
/api/domains/:id/pages	GET	Standard	List pages for a domain
/api/domains/:id/pages	POST	Standard	Add a page to monitor
/api/domains/:id/discover	POST	Heavy	Trigger page discovery
/api/domains/:id/crawl	POST	Heavy	Trigger immediate crawl
/api/jobs	GET	Standard	List recent jobs
/api/jobs/:id	GET	Standard	Get job status
/api/jobs/stats	GET	Standard	Get queue statistics
/api/usage	GET	Standard	Get current usage and quotas

SDKs and Libraries

Official SDKs are coming soon. In the meantime, use the OpenAPI spec to generate clients:

# Example: Generate TypeScript client with openapi-generator
npx @openapitools/openapi-generator-cli generate \
  -i https://api.trydiffy.com/openapi.json \
  -g typescript-fetch \
  -o ./diffy-client