Domains API

Manage your monitored domains programmatically. Add, update, delete, and list domains with full control over monitoring settings.

Overview

The Domains API allows you to manage all aspects of your SSL certificate monitoring. Each domain can have custom port settings, monitoring frequency, and notification preferences.

The number of domains you can monitor depends on your subscription tier. View pricing for details.

Endpoints

GET /api/v1/domains

List Domains

Retrieve a paginated list of all domains in your account with their current SSL status.

Query Parameters

Parameter Type Description
page integer Optional Page number for pagination (default: 1)
per_page integer Optional Items per page, max 100 (default: 20)
status string Optional Filter by status: active, inactive, expiring
grade string Optional Filter by SSL grade: A+, A, B, C, D, F
search string Optional Search domains by hostname

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/domains?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "domains": [
    {
      "id": 1,
      "hostname": "example.com",
      "port": 443,
      "ssl_grade": "A+",
      "ssl_score": 100,
      "certificate_expiry": "2025-06-15T12:00:00Z",
      "days_until_expiry": 154,
      "last_scan": "2025-01-12T10:30:00Z",
      "is_active": true,
      "monitoring_frequency": "daily",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /api/v1/domains/{id}

Get Domain

Retrieve detailed information about a specific domain including its SSL configuration and scan history.

Path Parameters

Parameter Type Description
id integer Required Path The unique domain ID

Example Request

cURL 
curl -X GET "https://myssl.info/api/v1/domains/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "domain": {
    "id": 1,
    "hostname": "example.com",
    "port": 443,
    "ssl_grade": "A+",
    "ssl_score": 100,
    "certificate": {
      "issuer": "Let's Encrypt Authority X3",
      "subject": "example.com",
      "valid_from": "2024-12-15T00:00:00Z",
      "valid_to": "2025-06-15T12:00:00Z",
      "serial_number": "03:AB:CD:EF:12:34:56:78",
      "fingerprint_sha256": "AB:CD:EF:..."
    },
    "last_scan": "2025-01-12T10:30:00Z",
    "is_active": true,
    "monitoring_frequency": "daily",
    "notifications_enabled": true,
    "alert_days_before_expiry": 30,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2025-01-12T10:30:00Z"
  }
}
POST /api/v1/domains

Add Domain

Add a new domain to your monitoring list. An initial SSL scan will be triggered automatically.

Request Body

Parameter Type Description
hostname string Required Body The domain hostname (e.g., "example.com")
port integer Body SSL port number (default: 443)
monitoring_frequency string Body Scan frequency: 5min, 15min, hourly, daily (depends on tier)
notifications_enabled boolean Body Enable email notifications (default: true)
alert_days_before_expiry integer Body Days before expiry to send alerts (default: 30)

Example Request

cURL 
curl -X POST "https://myssl.info/api/v1/domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "example.com",
    "port": 443,
    "monitoring_frequency": "daily",
    "notifications_enabled": true,
    "alert_days_before_expiry": 30
  }'

Example Response

201 Created 
{
  "domain": {
    "id": 2,
    "hostname": "example.com",
    "port": 443,
    "ssl_grade": null,
    "ssl_score": null,
    "is_active": true,
    "monitoring_frequency": "daily",
    "created_at": "2025-01-13T15:00:00Z"
  },
  "message": "Domain added successfully. Initial scan queued.",
  "scan_id": 456
}
PUT /api/v1/domains/{id}

Update Domain

Update monitoring settings for an existing domain.

Path Parameters

Parameter Type Description
id integer Required Path The unique domain ID

Request Body

Parameter Type Description
port integer Body SSL port number
monitoring_frequency string Body Scan frequency (depends on tier)
is_active boolean Body Enable/disable monitoring
notifications_enabled boolean Body Enable/disable notifications
alert_days_before_expiry integer Body Days before expiry to send alerts

Example Request

cURL 
curl -X PUT "https://myssl.info/api/v1/domains/1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monitoring_frequency": "hourly",
    "alert_days_before_expiry": 14
  }'

Example Response

200 OK 
{
  "domain": {
    "id": 1,
    "hostname": "example.com",
    "port": 443,
    "monitoring_frequency": "hourly",
    "alert_days_before_expiry": 14,
    "updated_at": "2025-01-13T15:30:00Z"
  },
  "message": "Domain updated successfully"
}
DELETE /api/v1/domains/{id}

Delete Domain

Remove a domain from monitoring. This will also delete all associated scan history and alerts.

Warning: This action is irreversible. All scan history and alerts for this domain will be permanently deleted.

Path Parameters

Parameter Type Description
id integer Required Path The unique domain ID

Example Request

cURL 
curl -X DELETE "https://myssl.info/api/v1/domains/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK 
{
  "message": "Domain deleted successfully",
  "deleted_domain_id": 1
}
POST /api/v1/domains/bulk-delete

Bulk Delete Domains

Delete multiple domains at once. Useful for cleanup operations.

Request Body

Parameter Type Description
domain_ids array[integer] Required Body Array of domain IDs to delete (max 100)

Example Request

cURL 
curl -X POST "https://myssl.info/api/v1/domains/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_ids": [1, 2, 3]
  }'

Example Response

200 OK 
{
  "message": "Domains deleted successfully",
  "deleted_count": 3,
  "deleted_ids": [1, 2, 3]
}

Error Codes

Domain-specific error codes you may encounter:

Code Message Description
400 Invalid hostname The provided hostname is not a valid domain
400 Invalid port Port must be between 1 and 65535
404 Domain not found The specified domain does not exist or you don't have access
409 Domain already exists This hostname:port combination is already being monitored
403 Domain limit reached You've reached your plan's domain limit. Upgrade to add more.
403 Frequency not allowed The requested monitoring frequency is not available on your plan

Related Endpoints

Scans API

Trigger and retrieve SSL scans

Uptime API

Monitor endpoint availability