Documentation

REST API

Manage your monitored domains programmatically. Available on Pro and Agency plans.

Authentication

All API requests require a Bearer token in the Authorization header. Generate your API key from your Account settings.

Authorization: Bearer your_api_key_here

Free plan accounts will receive a 403 Forbidden response. Upgrade to Pro or Agency for API access.

Base URL

https://xpiry.com/api/v1
GET /api/v1/domains

Returns all domains on your account, including their current SSL certificate status and domain registration details.

Example request

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

Example response

{
  "domains": [
    {
      "id": "abc-123",
      "domain": "example.com",
      "verified": true,
      "verification_status": "verified",
      "paused": false,
      "last_checked_at": "2026-04-04T12:00:00Z",
      "created_at": "2026-03-01T08:30:00Z",
      "ssl": {
        "status": "ok",
        "issuer": "/O=Let's Encrypt/CN=R3",
        "expires_at": "2026-07-01T00:00:00Z",
        "days_until_expiry": 88,
        "chain_valid": true
      },
      "domain_registration": {
        "registrar": "Namecheap, Inc.",
        "expires_at": "2027-03-01T00:00:00Z",
        "days_until_expiry": 331
      }
    }
  ]
}

SSL status values

ok warning critical expired

warning = expiry within 30 days, critical = within 7 days

POST /api/v1/domains

Add one or more domains to your account. Returns TXT record values you'll need to set on each domain for ownership verification.

Request body

Parameter Type Description
domain string A single domain name
domains array Multiple domain names (use instead of domain)

Example — single domain

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}' \
  https://xpiry.com/api/v1/domains

Example — multiple domains

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["example.com", "example.org"]}' \
  https://xpiry.com/api/v1/domains

Example response

{
  "created": [
    {
      "id": "abc-123",
      "domain": "example.com",
      "verified": false,
      "verification_status": "pending",
      "verification": {
        "txt_record_host": "_xpiry.example.com",
        "txt_record_value": "xpiry-verify=a1b2c3d4e5f6..."
      }
    }
  ],
  "errors": []
}

Verification: After creating a domain, add the TXT record shown in the response to your DNS. The record should be set at _xpiry.<your-domain> with the provided value. Then trigger verification from the dashboard or wait for automatic checking.

Response status codes

201 — All domains created successfully

207 — Some domains created, some failed (partial success)

422 — All domains failed to create

DELETE /api/v1/domains/:id

Permanently delete a domain and all its associated data (SSL certificates, check history, alerts).

Example request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://xpiry.com/api/v1/domains/DOMAIN_ID

Example response

{
  "message": "Domain 'example.com' deleted."
}

Error responses

All errors return a JSON object with an error key.

Status Description
401 Unauthorized Missing or invalid API key
403 Forbidden Account does not have API access (free plan)
404 Not Found Domain not found or does not belong to your account
422 Unprocessable Invalid request (bad domain name, limit reached, etc.)

Example error

{
  "error": "Invalid API key."
}

Rate limits

API requests are limited to 60 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.