Skip to main content

Generator Labs API (4.0)

The Generator Labs API is a RESTful web service API that lets customers manage their RBL monitoring hosts, certificate monitoring, contacts, and retrieve listing information.

Version 4.0 introduces a reorganized endpoint structure with proper REST verbs and resource grouping for improved consistency and usability.

Key Changes in v4.0

  • Reorganized endpoints under /rbl/, /cert/, and /contact/ resource groups
  • Proper REST verbs (POST for create, PUT for update, DELETE for delete)
  • Simplified endpoint paths with resource-based URLs
  • Backward compatible authentication and response formats

Dates and Time Zones

Dates and times in responses are in the time zone of the API application making the request, set on the application in the portal (Development > API Access > Applications). New applications use UTC; applications created before the setting existed use the time zone of the account owner. The MCP server uses the time zone of the API application it connects with.

Rate Limiting

API requests are subject to two levels of rate limiting:

  • Hourly limit: 1,000 requests per hour per API application
  • Per-second limit: varies by endpoint (100 RPS for reads, 50 RPS for writes, 10 RPS for starting RBL checks, 5 RPS for certificate checks on request)

Rate limit information is provided on every response using the following headers:

  • RateLimit-Limit: active policies, e.g. 1000;w=3600, 100;w=1 (1,000/hour and 100/second)
  • RateLimit-Remaining: requests remaining in the most restrictive active window
  • RateLimit-Reset: seconds until the most restrictive window resets

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Repeated failed authentication from one address is limited as well: after 120 failures in a minute, further requests from that address receive a 429 until the minute is over.

Idempotent Requests

Every request that creates something (POST on a collection), a contact resend or confirm, the certificate monitor DELETE, and the two check requests accept an Idempotency-Key header: a unique value of your own (a UUID, for example), up to 255 printable characters. If the request is sent again with the same key within 24 hours, the answer to the first request is returned, with the header Idempotent-Replayed: true, and nothing is created, sent, billed or deleted a second time. The same key with a different request is rejected with a 422. A request that was refused stores nothing, so a corrected retry is judged afresh. Use it whenever a client retries after a timeout.

Request Ids

Every response carries an X-Request-Id header. Send your own (1 to 64 letters, digits, -, _, . or :) and it is returned as sent; otherwise one is generated. Quote it when you contact support about a request: it identifies the request in our logs.

Conditional Requests

Every GET response carries a weak ETag. Send it back in If-None-Match on the next request for the same URL: when the answer has not changed you get 304 Not Modified with no body, and your copy is still current. The tag changes whenever the body would.

Field Selection

Any GET accepts ?fields= with a comma-separated list of the keys to keep in each object of data, for example ?fields=id,host,listed. A nested key is written with a dot (listings.host). The rest of the response (total, page, ...) is unchanged. A field name that no object has is rejected with a 422.

Compression

Responses are compressed with brotli or gzip when the request carries an Accept-Encoding header that allows it. Most HTTP libraries send one by default.

Error Responses

All responses include a consistent JSON body with a status_code (which mirrors the HTTP status) and a status_message:

{
  "status_code": 404,
  "status_message": "A description of the error."
}

Status Codes:

  • 200 - Success
  • 400 - Bad request (malformed or invalid input, e.g. an invalid SID, or the SID of a different kind of object)
  • 401 - Authentication failed
  • 403 - Forbidden (IP address restriction, or a feature not available on your plan)
  • 404 - Not found (the requested resource, or the endpoint itself, does not exist)
  • 405 - Method not allowed (an action that changes something was requested with GET)
  • 409 - Conflict (the resource is in a state that does not allow the action, or a request with the same Idempotency-Key is still being processed)
  • 413 - The request body is larger than 1 MB
  • 422 - Validation failed (the input was understood but did not pass validation)
  • 429 - Rate limit exceeded, or a transient service condition (e.g. the service is temporarily unavailable). In both cases the API sends a Retry-After header and the RateLimit-* headers; clients should back off and retry rather than treat it as a hard failure.
  • 500 - Server error

PHP SDK

The PHP SDK can be installed via composer:

composer require generatorlabs/sdk

Or the source code can be downloaded directly from the GitHub repository.

The PHP SDK requires PHP >= 8.1 and the PHP JSON extension.

Node.js SDK

The Node.js SDK can be installed via npm:

npm install generatorlabs

Or the source code can be downloaded directly from the GitHub repository.

The Node.js SDK requires Node.js >= 18.0.

Python SDK

The Python SDK can be installed via pip:

pip install generatorlabs

Or the source code can be downloaded directly from the GitHub repository.

The Python SDK supports Python >= 3.8.

Go SDK

The Go SDK can be installed via go get:

go get github.com/generator-labs/go-sdk/v2

Or the source code can be downloaded directly from the GitHub repository.

The Go SDK requires Go >= 1.21.

Ruby SDK

The Ruby SDK can be installed via gem:

gem install generatorlabs

Or the source code can be downloaded directly from the GitHub repository.

The Ruby SDK requires Ruby >= 3.0.

Check

Start manual, real-time checks against hosts on your account or one-off IP addresses/domains.

Start Check

Starts a manual check for a provided Host.

This process is asynchronous, in that it returns right away, returning a check id that you may use to poll for subsequent updates. This is done because a full RBL check may take some time to process, and this avoids blocking the API response.

A manual check is billed, so this request can be made safe to retry: send an Idempotency-Key header with a unique value of your own (a UUID, for example). If the request is sent again with the same key, the check that was already started is returned, with the header Idempotent-Replayed: true, and no second check is started or billed. A key is remembered for 24 hours, and belongs to one request: the same key with a different host is rejected with a 422.

Rate limit: 10 requests/second

Authorizations:
basicAuth
header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value returns the check that was already started instead of starting another.

Request Body schema: application/x-www-form-urlencoded
required
host
required
string^(?:(?:[0-9]{1,3}\.){3}[0-9]{1,3}|[a-zA-Z0-9]...

The host value; either an IP address, domain name, or host SID (to use an existing host).

callback
string <uri>

An HTTP callback URL that we will post to once the check request completes.

details
boolean
Default: false

A flag indicating if the RBL details should be returned with the response.

Responses

Callbacks

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/check/start.json \
    -u 'your_account_sid:your_auth_token' \
    -d host='10.10.10.11' \
    -d callback='https://your.website.com/callback.php' \
    -d details=true

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Check started successfully.",
  • "data": {
    }
}

Callback payload samples

Callback
POST: {$request.body#/callback}
Content type
application/json
{
  • "event_sid": "TA9dbf5e2f7e924418a6d6b483a584adcf",
  • "event_type": "rbl.host.check.completed",
  • "event_date": "2025-12-22T23:43:52+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": true,
  • "total": 1,
  • "details": [
    ]
}

Check Status

Gets the status of a previously started manual check.

You can use the check id returned from /4.0/rbl/check/start to poll for check status in real-time.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^PP[0-9a-f]{64}$
Example: PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a

Check id returned from /check/start.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

details
boolean
Default: false

A flag indicating if the RBL details should be returned with the response.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/check/status/{id}.json?details=true \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Check status retrieved successfully.",
  • "data": {
    }
}

Listings

Retrieve all hosts currently listed on one or more RBLs.

Listings

Return a full list of all the hosts that are currently listed on one or more data sources.

This data mirrors the response returned by the /4.0/hosts API request. The only difference, is the /4.0/listings request only returns hosts that are currently listed, instead of all hosts.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/listings.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Listings",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "total_listed": 1,
  • "data": [
    ]
}

Hosts

Manage hosts configured on your account for RBL monitoring.

List Hosts

Returns a full list of hosts configured on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/hosts.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Hosts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "total_listed": 1,
  • "data": [
    ]
}

Create Host

Create a new host on your account.

When using the ip_range host type, or when adding hosts by subnet, multiple hosts may be created and returned in the data response object.

Rate limit: 50 requests/second

Authorizations:
basicAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
host
required
string^(?:(?:[0-9]{1,3}\.){3}[0-9]{1,3}(?:\/[0-9]{1...

Host value (IP/domain/subnet) based on type.

name
required
string [ 1 .. 255 ] characters

Label for the Host.

profile
required
string^RP[0-9a-f]{32}$

Monitoring Profile id to use on this Host.

contact_group
required
string

Comma-separated list of one or more Contact Group SIDs to use for this Host.

tags
string

Comma-separated list of tags to assign to the host.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My New Host' \
    -d host='10.10.10.11' \
    -d profile='RP9f8e7d6c5b4a3210fedcba0987654321' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host added successfully.",
  • "data": [
    ]
}

Get Host

Returns details for an individual host.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Hosts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "total_listed": 1,
  • "data": [
    ]
}

Update Host

Updates an existing host on your account. A name that another of your hosts already has is rejected.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

The label for this Host.

profile
string^RP[0-9a-f]{32}$

The unique SID of the Monitoring Profile to use for this Host.

contact_group
string

Comma-separated list of one or more Contact Group SIDs to use for this Host.

tags
string

Comma-separated list of tags to assign to the host.

Responses

Request samples

curl -X PUT https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Updated Host' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host updated successfully."
}

Delete Host

Deletes an existing host on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X DELETE https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host deleted successfully."
}

Pause Host

Pauses a Host, which temporarily stops all checks on this Host.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host paused successfully."
}

Re-Activate Host

Re-activates a Host after it was paused. We will resume processing checks on this host.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host activated successfully."
}

Monitoring Profiles

Manage monitoring profiles that control which RBLs are checked for hosts.

Note: These features are only available to customers on a paid plan.

List Profiles

Returns a full list of monitoring profiles configured on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/profiles.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Create Profile

Create a new monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
name
required
string [ 1 .. 255 ] characters

Label for the Profile.

entries
string

Comma-separated list of RBL SIDs to include in this profile.

is_default
boolean

Set this profile as the account default.

frequency
required
string
Enum: "1_hour" "2_hours" "3_hours" "6_hours" "12_hours" "24_hours" "48_hours" "weekly" "2_weeks"

Check frequency interval. Required for Ultimate accounts; ignored on other tiers (which use the package's fixed interval).

sync_method
string
Enum: "stay_in_sync" "use_my_selections"

RBL sync method. Optional — automatically set to use_my_selections when entries is provided, otherwise defaults to stay_in_sync.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/profiles.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Custom Profile' \
    -d entries='RB1234567890abcdef1234567890abcdef,RB0987654321fedcba0987654321fedcba'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profile added successfully.",
  • "data": {
    }
}

Get Profile

Returns details for an individual monitoring profile.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RP[0-9a-f]{32}$
Example: RP9f8e7d6c5b4a3210fedcba0987654321

Unique Profile SID.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Profile

Updates an existing monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RP[0-9a-f]{32}$
Example: RP9f8e7d6c5b4a3210fedcba0987654321

Unique Profile SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

The label for this Profile.

entries
string

Comma-separated list of RBL SIDs to include in this profile. Sending entries does not change the profile's sync_method; send that as well to change it.

is_default
boolean

Set this profile as the account default. An account always has a default profile: to change it, set is_default to true on another profile. Setting it to false on the default profile is rejected.

frequency
string
Enum: "1_hour" "2_hours" "3_hours" "6_hours" "12_hours" "24_hours" "48_hours" "weekly" "2_weeks"

Check frequency interval.

sync_method
string
Enum: "stay_in_sync" "use_my_selections"

RBL sync method. Automatically set to 'use_my_selections' when entries are provided.

Responses

Request samples

curl -X PUT https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='Updated Profile Name' \
    -d entries='RB1234567890abcdef1234567890abcdef,RB0987654321fedcba0987654321fedcba'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profile updated successfully."
}

Delete Profile

Deletes an existing monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RP[0-9a-f]{32}$
Example: RP9f8e7d6c5b4a3210fedcba0987654321

Unique Profile SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X DELETE https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring profile deleted successfully."
}

Sources

Retrieve all active RBL sources on the system, including custom RBLs you've added.

Note: These features are only available to customers on a paid plan.

List Sources

Returns a full list of all active RBL sources on the system, including custom RBLs you've added.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/sources.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Data Sources",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "data": []
}

Create Source

Create a new custom RBL source on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
host
required
string^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9](?:\...

Hostname of the RBL server.

type
required
string
Enum: "rbl" "rbl_v6" "uribl"

The type of the data source.

custom_codes
string

Comma-separated list of custom DNS response codes (e.g. 127.0.0.2,127.0.0.3). Used to define which response codes indicate a listing.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/sources.json \
    -u 'your_account_sid:your_auth_token' \
    -d host='custom.rbl.example.com' \
    -d type='rbl' \
    -d custom_codes='127.0.0.2,127.0.0.3'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL added successfully.",
  • "data": {
    }
}

Get Source

Returns details for an individual RBL source.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Data Sources",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": []
}

Update Source

Updates an existing RBL source on your account. Only the fields you send are changed: custom_codes that are not sent are kept. A paused source can still be viewed, updated, resumed and deleted, and is included in the list of sources.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
optional
host
string^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9](?:\...

The hostname of the RBL server.

type
string
Enum: "rbl" "rbl_v6" "uribl"

The type of the data source.

custom_codes
string

Comma-separated list of custom DNS response codes (e.g. 127.0.0.2,127.0.0.3). Used to define which response codes indicate a listing.

Responses

Request samples

curl -X PUT https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d host='updated.rbl.example.com' \
    -d custom_codes='127.0.0.2,127.0.0.3'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL updated successfully."
}

Delete Source

Deletes an existing RBL source on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X DELETE https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL deleted successfully."
}

Pause Source

Pauses an RBL source, temporarily excluding it from all checks.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/sources/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL paused successfully."
}

Resume Source

Resumes a paused RBL source, re-enabling it in all checks.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/rbl/sources/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL activated successfully."
}

Errors

Retrieve active certificate errors and findings across all monitors.

List Certificate Errors

Returns the active monitors that have a warning or an error their profile alerts on, each with those warnings and errors, worst first. Paused and archived monitors are left out.

A finding is listed only when it is a warning or an error and the monitor's profile alerts on it, the same rule as the alert emails. Each finding comes under one of the profile's alert settings:

Findings Profile setting
Connection (CERT_NET*) alert_on_connection_failure
Misconfigurations (CERT_CON01) alert_on_misconfigurations
Certificate Flapping (CERT_CON02) alert_on_flapping
Expiration (CERT_EXP*, including Expires Soon and Expired) alert_on_expiration
Name check (CERT_HST*) alert_on_name_mismatch
Chain of trust and revocation (CERT_TRU*, CERT_REV*) alert_on_ca_failure
Integrity (CERT_SIG*, CERT_KEY*) Alert on integrity / configuration failures (portal)
CAA (CERT_CAA*) alert_on_caa_failure

Notices aren't listed, and a finding you've dismissed on a monitor (in the portal or with POST /cert/findings/dismiss) is left out. To list every current finding, notices and findings the profile doesn't alert on included, use GET /cert/findings.

Besides the findings from the last check, this includes Expires Soon (CERT_EXP01) while the certificate the last check read is inside its profile's warning period. When the last check read no certificate, Expires Soon isn't listed, as no expiry alert is sent then; the connection failure is. It also includes Certificate Flapping (CERT_CON02) when the certificate keeps changing between checks, and warnings such as CAA Not Found (CERT_CAA01) whatever the expiry date.

The list is paged by monitor (page, page_size, up to 100 monitors a page), and total_errors counts the warnings and errors on the page returned.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/cert/errors.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Errors",
  • "total_errors": 3,
  • "data": [
    ]
}

Count Certificate Errors

Returns the number of warnings and errors the account's monitor profiles alert on, as plain text: the same monitors and findings as GET /cert/errors (active monitors only, warning or worse, only the findings the monitor's profile alerts on, dismissed findings left out), counted across every page: the sum of total_errors over all of its pages. Turning off an alert setting in a profile takes those findings out of the count, so a monitoring plugin stops reporting them. 0 means nothing to report. It's meant for monitoring plugins, such as the Nagios and Zabbix plugins, which read the body as a number.

A request that fails answers -1 in the body, with the error's status code.

Rate limit: 100 requests/second

Authorizations:
basicAuth
header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/cert/errors/count \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
text/plain
3

List Certificate Findings

Returns the active monitors that have any current certificate finding, each with every one of its findings, worst first: errors, warnings and notices, whatever the profile's alert settings, as the portal's Findings page shows them. Paused and archived monitors are left out, and so is a finding you've dismissed on a monitor, in the portal or with POST /cert/findings/dismiss, unless you set dismissed=1.

With dismissed=1, each active monitor also lists the findings dismissed from it, after its other findings, with dismissed: true and alerts: false, and a monitor whose only findings are dismissed is listed too. Use it to find what to restore with POST /cert/findings/restore.

Each finding's alerts says whether the monitor's profile alerts on it, that is, whether it is listed by GET /cert/errors and counted by GET /cert/errors/count. Notices never alert. When the last check read no certificate, Expires Soon (CERT_EXP01) is still listed, judged by the last certificate seen, with alerts: false, as no expiry alert is sent without a certificate; the connection failure alerts instead.

Monitors are in name order. The list is paged by monitor (page, page_size, up to 100 monitors a page), and total_findings counts the findings (not monitors) on the page returned, dismissed ones included when they're listed.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

dismissed
string
Enum: "1" "true"

Set to 1 or true to also list the findings dismissed from each monitor, after its other findings.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/cert/findings.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
Example
{
  • "status_code": 200,
  • "status_message": "Certificate Findings",
  • "total_findings": 4,
  • "data": [
    ]
}

Dismiss Certificate Findings

Dismisses one or more findings on the account's monitors, the same as dismissing them in the portal, for findings you've decided not to act on.

Leave monitors out to dismiss the findings from every active monitor that has them now. When you name monitors, the findings are dismissed from each of them, whatever its status, whether or not it has them now, so they stay dismissed if they appear later.

Only these findings can be dismissed, the same as in the portal:

Key Label
CERT_CAA01 CAA Not Found
CERT_CAA02 CAA Not Specific
CERT_LIF01 Long Reg Period
CERT_HST01 Matched CN, No SAN
CERT_TRU03 Root Sent

A dismissed finding is left out of the monitor's findings, GET /cert/findings, GET /cert/errors, GET /cert/errors/count and the alerts, until it's restored with POST /cert/findings/restore. Each finding's dismissible in GET /cert/findings says whether it can be dismissed.

data lists the monitors that changed, in hostname order, each with the finding keys changed on it, and total counts them.

This request must be a POST; a GET or HEAD is answered with a 405.

Rate limit: 100 requests/second

Authorizations:
basicAuth
header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
finding_id
required
string

The finding key to dismiss, or several separated by commas.

monitors
string

Certificate Monitor SIDs separated by commas. Leave it out to dismiss from every active monitor that has the finding now.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/cert/findings/dismiss.json \
    -u 'your_account_sid:your_auth_token' \
    -d finding_id='CERT_CAA01'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Findings dismissed successfully.",
  • "total": 2,
  • "data": [
    ]
}

Restore Certificate Findings

Restores one or more dismissed findings on the account's monitors, the same as Restore in the portal.

Leave monitors out to restore the findings on every monitor they're dismissed from, or name the monitors to restore them on.

Only these findings can be dismissed and restored, the same as in the portal:

Key Label
CERT_CAA01 CAA Not Found
CERT_CAA02 CAA Not Specific
CERT_LIF01 Long Reg Period
CERT_HST01 Matched CN, No SAN
CERT_TRU03 Root Sent

A restored finding is back in the monitor's findings, GET /cert/findings, GET /cert/errors, GET /cert/errors/count and the alerts, by the same rules as any other finding.

data lists the monitors that changed, in hostname order, each with the finding keys changed on it, and total counts them.

This request must be a POST; a GET or HEAD is answered with a 405.

Rate limit: 100 requests/second

Authorizations:
basicAuth
header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
finding_id
required
string

The finding key to restore, or several separated by commas.

monitors
string

Certificate Monitor SIDs separated by commas. Leave it out to restore on every monitor the finding is dismissed from.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/cert/findings/restore.json \
    -u 'your_account_sid:your_auth_token' \
    -d finding_id='CERT_CAA01'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Findings restored successfully.",
  • "total": 2,
  • "data": [
    ]
}

Monitors

Manage certificate monitors configured on your account for TLS/SSL certificate monitoring.

List Certificate Monitors

Returns a full list of certificate monitors configured on your account. Archived monitors are left out; pass status=archived to list only the archived ones.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

status
string
Value: "archived"

Set to archived to list only the archived monitors.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/cert/monitors.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitors",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "data": [
    ]
}

Create Certificate Monitor

Create a new certificate monitor on your account. Only hostname, protocol and name are required: without a profile the monitor uses the account's default profile, and without contact groups the account's default contact group.

The hostname is checked the same way as in the portal. It can't carry a protocol prefix other than the protocol's own (https:// for https, which is removed), and a custom port goes on the hostname (mail.example.com:2500, [2001:db8::1]:8443). On a profile checked from our system, a name also has to include its domain, resolve, and resolve only to public addresses; a profile checked by a monitoring agent skips the lookup. A failed check, a name already used by another monitor that isn't archived, the same hostname and protocol as another monitor that isn't archived, or an account at its monitor limit, is rejected with a 422.

Rate limit: 50 requests/second

Authorizations:
basicAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
hostname
required
string

The hostname or IP address to monitor, with an optional :port for a port other than the protocol's default (up to 512 characters).

protocol
required
string
Enum: "https" "smtps" "smtp" "imaps" "imap" "pops" "pop" "lmtp" "ftps" "ftp" "ldaps" "ldap" "mysql" "postgresql" "sips"

The protocol to use when checking the certificate.

name
required
string [ 1 .. 256 ] characters

Label for the Certificate Monitor. Must be unique among the account's monitors that aren't archived.

profile
string^CP[0-9a-f]{32}$

Certificate Monitoring Profile id to use on this monitor. Defaults to the account's default profile.

contact_group
string

One Contact Group id to send this monitor's alerts to. Use contact_groups for more than one. Defaults to the account's default contact group.

contact_groups
string

Comma-separated list of Contact Group ids to send this monitor's alerts to. Used instead of contact_group when both are sent.

tags
string

Comma-separated list of tags for organization.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/cert/monitors.json \
    -u 'your_account_sid:your_auth_token' \
    -d hostname='example.com' \
    -d protocol='https' \
    -d name='My SSL Certificate' \
    -d profile='CP15d4e891d784977cacbfcbb00c48f133' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web,ssl'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor added successfully.",
  • "data": {
    }
}

Get Certificate Monitor

Returns details for an individual certificate monitor.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM62944aeeee2b46d7a28221164f38976a

Unique Certificate Monitor SID.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitors",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Certificate Monitor

Updates an existing certificate monitor on your account. Only the fields you send are changed; when contact_group or contact_groups is sent, it replaces the monitor's contact groups. A monitor's hostname and protocol can't be changed: add a new monitor instead. Moving a monitor from a profile checked by a monitoring agent to one checked from our system checks its hostname the same way as adding it there, and a name already used by another monitor that isn't archived is rejected with a 422.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM62944aeeee2b46d7a28221164f38976a

Unique Certificate Monitor SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 256 ] characters

The label for this Certificate Monitor.

profile
string^CP[0-9a-f]{32}$

The unique SID of the Certificate Monitoring Profile to use for this monitor.

contact_group
string

One Contact Group SID to use for this monitor. Use contact_groups for more than one.

contact_groups
string

Comma-separated list of one or more Contact Group SIDs to use for this monitor. Used instead of contact_group when both are sent.

tags
string

Comma-separated list of tags for organization.

Responses

Request samples

curl -X PUT https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Updated Monitor' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web,ssl'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor updated successfully."
}

Delete Certificate Monitor

Archives or deletes a certificate monitor on your account. The first delete archives the monitor: it's no longer checked or billed, it's left out of the monitor list (unless you ask for status=archived), and its reports and history are kept. Resume it to make it active again. Deleting an archived monitor removes it for good.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM62944aeeee2b46d7a28221164f38976a

Unique Certificate Monitor SID.

header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X DELETE https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
Example
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor archived successfully. Delete it again to remove it permanently."
}

Pause Certificate Monitor

Pauses a certificate monitor on your account: it's no longer checked or billed. Pausing an archived monitor brings it back from the archive as a paused monitor, so it counts toward the account's monitor limit again; an account at its limit is rejected with a 422.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM4f3e2d1c0b9a8776655443322110fedc

Unique Certificate Monitor SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor paused successfully."
}

Resume Certificate Monitor

Resumes a paused or archived certificate monitor on your account. A resumed archived monitor counts toward the account's monitor limit again; an account at its limit is rejected with a 422.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM4f3e2d1c0b9a8776655443322110fedc

Unique Certificate Monitor SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor activated successfully."
}

Check Certificate Monitor Now

Requests a check of a certificate monitor now, for example right after a certificate was renewed.

This process is asynchronous: the check is queued and the request returns right away. The result shows up on the monitor (last_checked, status, days_remaining) and in the certificate errors a few seconds later.

There is no charge beyond the monitor's normal daily charge. A check on request also runs while the account's scheduled checks are paused.

A monitor can be checked on request at most once a minute, and 10 times in any 24 hours; an account can request 100 checks in any 24 hours. Requests over a limit are rejected with a 429 and a Retry-After header.

A paused or archived monitor, an account on hold, and a monitor whose profile is checked by monitoring agents with none assigned are rejected with a 422.

This request can be made safe to retry: send an Idempotency-Key header with a unique value of your own (a UUID, for example). If the request is sent again with the same key, the first answer is returned, with the header Idempotent-Replayed: true, and no second check is queued; its status is the queued check's current status, completed once the check has run, otherwise queued. A key is remembered for 24 hours, and belongs to one request: the same key for a different monitor is rejected with a 422. Without a key, a repeat while the first request is still waiting returns that request.

Rate limit: 5 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM4f3e2d1c0b9a8776655443322110fedc

Unique Certificate Monitor SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value returns the first answer instead of queuing another check.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/check.json \
    -u 'your_account_sid:your_auth_token' \
    -H 'Idempotency-Key: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor check queued successfully.",
  • "data": {
    }
}

Cert Profiles

Manage certificate monitoring profiles that control validation rules and alert thresholds.

List Certificate Profiles

Returns a full list of certificate monitoring profiles configured on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/cert/profiles.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "data": [
    ]
}

Create Certificate Profile

Create a new certificate monitoring profile on your account. An alert_on_* field you leave out gets its default below. The alert fields take true, 1, on or yes to switch an alert on; any other value, including false and 0, switches it off.

Rate limit: 50 requests/second

Authorizations:
basicAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
name
required
string [ 1 .. 256 ] characters

Label for the Certificate Profile.

expiration_thresholds
required
string

Comma-separated list of days before expiration to send alerts (e.g., '30,14,7'): 1 to 10 values, each a whole number from 0 to 90. Anything else, including empty entries ('30,14,') and decimals, is rejected with a 422.

alert_on_expiration
boolean
Default: true

Send alerts when certificate is expiring based on thresholds.

alert_on_name_mismatch
boolean
Default: true

Send alerts when certificate hostname doesn't match the requested hostname.

alert_on_ca_failure
boolean
Default: true

Send alerts when certificate authority validation fails.

alert_on_connection_failure
boolean
Default: true

Send alerts when unable to establish a connection to check the certificate.

alert_on_caa_failure
boolean
Default: false

Send alerts when CAA (Certificate Authority Authorization) record validation fails.

alert_on_misconfigurations
boolean
Default: true

Send alerts on certificate misconfigurations.

alert_on_changes
boolean
Default: true

Send alerts when certificate changes are detected.

fingerprint_enabled
boolean
Default: true

After the certificate check, send a few standard protocol commands (EHLO / HELP, CAPABILITY, FEAT, a GET of a page that doesn't exist and of the home page, ...) to identify the server software and version. These are visible in your server logs.

is_default
boolean

Set this profile as the account default (true or 1).

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/cert/profiles.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Certificate Profile' \
    -d expiration_thresholds='30,14,7' \
    -d alert_on_expiration=true \
    -d alert_on_name_mismatch=true \
    -d alert_on_misconfigurations=true \
    -d alert_on_changes=true

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profile added successfully.",
  • "data": {
    }
}

Get Certificate Profile

Returns details for an individual certificate monitoring profile.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CP[0-9a-f]{32}$
Example: CP79b597e61a984a35b5eb7dcdbc3de53c

Unique Certificate Profile SID.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Certificate Profile

Updates an existing certificate monitoring profile on your account. Only the fields you send are changed, including each alert_on_* field: true, 1, on or yes switches that alert on, any other value (including false and 0) switches it off, and a field you leave out stays as it is. An account always has a default profile: to change it, set is_default to true on another profile; setting it to false on the default profile is rejected.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CP[0-9a-f]{32}$
Example: CP79b597e61a984a35b5eb7dcdbc3de53c

Unique Certificate Profile SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 256 ] characters

The label for this Certificate Profile.

expiration_thresholds
string

Comma-separated list of days before expiration to send alerts (e.g., '30,14,7'): 1 to 10 values, each a whole number from 0 to 90. Anything else, including empty entries ('30,14,') and decimals, is rejected with a 422.

alert_on_expiration
boolean

Send alerts when certificate is expiring based on thresholds.

alert_on_name_mismatch
boolean

Send alerts when certificate hostname doesn't match the requested hostname.

alert_on_ca_failure
boolean

Send alerts when certificate authority validation fails.

alert_on_connection_failure
boolean

Send alerts when unable to establish a connection to check the certificate.

alert_on_caa_failure
boolean

Send alerts when CAA (Certificate Authority Authorization) record validation fails.

alert_on_misconfigurations
boolean

Send alerts on certificate misconfigurations.

alert_on_changes
boolean

Send alerts when certificate changes are detected.

fingerprint_enabled
boolean

After the certificate check, send a few standard protocol commands (EHLO / HELP, CAPABILITY, FEAT, a GET of a page that doesn't exist and of the home page, ...) to identify the server software and version. These are visible in your server logs.

is_default
boolean

Set this profile as the account default (true or 1).

Responses

Request samples

curl -X PUT https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Updated Profile' \
    -d expiration_thresholds='45,14,7' \
    -d alert_on_misconfigurations=true \
    -d alert_on_changes=true

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profile updated successfully."
}

Delete Certificate Profile

Deletes an existing certificate monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CP[0-9a-f]{32}$
Example: CP79b597e61a984a35b5eb7dcdbc3de53c

Unique Certificate Profile SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X DELETE https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profile deleted successfully."
}

Contacts

Manage individual contacts configured on your account.

Get a List of Contacts

Returns a full list of contacts on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/contact/contacts.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contacts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "data": [
    ]
}

Create Contact

Create a new contact on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
contact
required
string

The contact value based on the type.

type
required
string
Enum: "email" "sms" "pushover" "pagerduty" "slack" "datadog" "discord" "telegram" "endpoint" "aws-sns" "aws-cloudwatch"

Contact type (email, sms, slack, webhook, etc.)

schedule
required
string
Deprecated
Enum: "every_check" "start_and_end" "while_listed"

The notification schedule. This field is being phased out and will be removed in a future API version.

contact_group
required
string

Comma-separated list of Contact Group SIDs to assign to this Contact. Example: "CONTACTGROUPsid1,CONTACTGROUPsid2"

args
object or null

Additional configuration for the contact type (e.g. endpoint URL, Datadog API key). Required for some contact types. Write-only: it is never returned in responses.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts.json \
    -u 'your_account_sid:your_auth_token' \
    -d contact='admin@example.com' \
    -d type='email' \
    -d schedule='every_check' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact added successfully.",
  • "data": {
    }
}

Get Contact

Returns the details for a single contact.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

The unique SID of the Contact.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contacts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Contact

Updates an existing contact on your account.

A contact's value (the address, number or URL its alerts are sent to) can not be changed: it was confirmed by whoever receives the alerts. To change it, delete the contact and add a new one. Only the fields you send are changed; a contact whose contact_group is not sent keeps its groups.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

Unique Contact SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
optional
schedule
string
Deprecated
Enum: "every_check" "start_and_end" "while_listed"

The notification schedule. This field is being phased out and will be removed in a future API version.

contact_group
string

Comma-separated list of Contact Group SIDs to assign to this Contact. Example: "CONTACTGROUPsid1,CONTACTGROUPsid2"

Responses

Request samples

curl -X PUT https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact updated successfully."
}

Delete Contact

Deletes an existing contact on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

Unique Contact SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X DELETE https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact deleted successfully."
}

Pause Contact

Pause a contact. This will temporarily stop notifications to this contact.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COd3dca251d33135e0a518d7c49b89dc61

The unique SID of the Contact.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact paused successfully."
}

Re-Activate Contact

Re-activate a contact after it was paused. We will resume sending notifications to this contact.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COd3dca251d33135e0a518d7c49b89dc61

The unique SID of the Contact.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact activated successfully."
}

Resend Confirmation

Resends the authorization confirmation to the specified contact. The contact must be in 'pending' status.

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COd3dca251d33135e0a518d7c49b89dc61

The unique SID of the Contact.

header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/resend.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact authorization re-sent successfully."
}

Confirm Contact

Confirms a pending contact using a confirmation code.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

The unique SID of the Contact.

header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
authcode
required
string

Confirmation token delivered to the Contact.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/confirm.json \
    -d authcode='3Kx3se' \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact authorized successfully."
}

Contact Groups

Manage contact groups configured on your account.

Get a List of Contact Groups

Returns a full list of contact groups on your account.

The is_default flag defines which contact group is marked as default. The default contact group is used on new hosts and contacts when a contact group ID is omitted.

Only one contact group can be marked a default. If you add a new contact group, or update an existing contact group, and set is_default to 1, then any existing default contact group will no longer be set as default.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/contact/groups.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact Groups",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Create Contact Group

Create a new contact group on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55

A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with Idempotent-Replayed: true instead of doing the work again.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
required
name
required
string [ 1 .. 255 ] characters

Name for the contact group.

is_default
boolean

Set this Contact Group as the default.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/contact/groups.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='Primary Contacts'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact group added successfully.",
  • "data": {
    }
}

Get Contact Group

Return details for a single Contact Group, based on the SID passed.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CG[0-9a-f]{32}$
Example: CG4f3e2d1c0b9a8776655443322110fedc

The unique SID of the Contact Group.

query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -G https://api.generatorlabs.com/4.0/contact/groups/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact Groups",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Contact Group

Updates an existing contact group on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CG[0-9a-f]{32}$
Example: CG4f3e2d1c0b9a8776655443322110fedc

Unique Contact Group SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

Name for the contact group.

is_default
boolean

Set this Contact Group as the default.

Responses

Request samples

curl -X PUT https://api.generatorlabs.com/4.0/contact/groups/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='Updated Contact Group'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact group updated successfully."
}

Delete Contact Group

Deletes an existing contact group on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CG[0-9a-f]{32}$
Example: CG4f3e2d1c0b9a8776655443322110fedc

Unique Contact Group SID.

header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X DELETE https://api.generatorlabs.com/4.0/contact/groups/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact Group deleted successfully."
}

Account

Read your account's balance and usage, and pause or resume its scheduled checks.

Get Account

Returns your account: its balance, whether its scheduled checks are running, and how much of what your plan allows is in use.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl https://api.generatorlabs.com/4.0/account.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Account retrieved successfully.",
  • "data": {
    }
}

Get Account Balance

Returns your account balance as a plain number with four decimals, followed by a newline, for use in monitoring plugins and scripts. The body is -1 when the balance can't be read.

Rate limit: 100 requests/second

Authorizations:
basicAuth
header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl https://api.generatorlabs.com/4.0/account/balance \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
text/plain
80.1226

Pause Account Checks

Stops the scheduled checks of every host and certificate monitor on your account. A check that is requested by hand (a manual RBL check, or a certificate monitor check on request) still runs while they are paused.

Rate limit: 10 requests/second

Authorizations:
basicAuth
header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/account/checks/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Account checks paused successfully."
}

Resume Account Checks

Restarts the scheduled checks of every host and certificate monitor on your account. Has no effect when they are already running.

Rate limit: 10 requests/second

Authorizations:
basicAuth
header Parameters
X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl -X POST https://api.generatorlabs.com/4.0/account/checks/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Account checks resumed successfully."
}

Get Account Usage

Returns what your account was charged, by month and service, newest first.

Rate limit: 50 requests/second

Authorizations:
basicAuth
query Parameters
fields
string
Example: fields=id,host,listed

Comma-separated list of the keys to keep in each object of data; a nested key is written with a dot. A key no object has is rejected with a 422.

months
integer [ 1 .. 24 ]
Default: 12

How many months to return, the current month included.

header Parameters
If-None-Match
string
Example: W/"53b07f718e365c7743d1108cd2de9676"

The ETag of the copy you hold. When the answer has not changed, the response is 304 Not Modified with no body.

X-Request-Id
string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$
Example: deploy-42-step-3

Your id for this request, returned as sent. One is generated when it is missing or not usable.

Responses

Request samples

curl https://api.generatorlabs.com/4.0/account/usage.json?months=3 \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Account usage retrieved successfully.",
  • "months": 3,
  • "total": 2,
  • "data": [
    ]
}

Webhook Verification

All webhook requests include an X-Webhook-Signature header that can optionally be used to verify the authenticity of the request. Each webhook endpoint has a unique Signing Secret, available in the Portal under Dev > Webhooks > Edit.

The header format is:

X-Webhook-Signature: t=1738900000,v1=5257a869...

Where t is the Unix timestamp and v1 is the HMAC-SHA256 signature computed over {t}.{body} using the webhook's Signing Secret.

To verify a webhook request:

  1. Extract t and v1 from the X-Webhook-Signature header
  2. Compute HMAC-SHA256(signing_secret, "{t}.{raw_body}")
  3. Compare the result with v1 using a constant-time comparison
  4. Optionally reject requests where t is older than 5 minutes

RBL Events

Webhook events triggered during RBL monitoring checks.

Host Check Started Webhook

Triggered at the start of a check, when one of your hosts is checked.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.check.started",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    }
}

Host Check Completed Webhook

Triggered at the end of a check, when one of your hosts is checked. This event is trigger whether or not the host is listed.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

listed
required
boolean

If the Host is listed or not.

total
required
integer
Default: 0

The total number of data sources this Host is currently listed on.

required
Array of objects (webhook_rbl_details)

An array of data sources that matched this Host. This can be empty if there were no matches.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.check.completed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": true,
  • "total": 1,
  • "details": [
    ]
}

Host Listed Webhook

Triggered at the end of a check, when one of your hosts is listed. This event is only triggered in the event the host is listed.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

listed
required
boolean

If the Host is listed or not. This will always be true for this event.

total
required
integer
Default: 0

The total number of data sources this Host is currently listed on.

required
Array of objects (webhook_rbl_details)

An array of data sources that matched this Host. This can be empty if there were no matches.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.listed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": true,
  • "total": 1,
  • "details": [
    ]
}

Host De-Listed Webhook

Triggered at the end of a check, when one of your hosts is de-listed. This event will only trigger in the event the host is de-listed.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

listed
required
boolean

If the Host is listed or not. This will always be false for this event.

total
required
integer
Default: 0

The total number of data sources this Host is currently listed on. This will always be 0 for this event.

details
required
Array of arrays

An array of data sources that matched this Host. This will always be empty for this event.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.delisted",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": false,
  • "total": 0,
  • "details": [ ]
}

Billing Events

Webhook events triggered related to accounts, billing, and payments.

Balance Alert Webhook

Triggered when your account balance goes below your configured alert threshold.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

balance
required
string

Your current account balance (in USD).

alert_threshold
required
string

Your configured low-balance alert threshold (in USD).

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.balance.alert",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "balance": "12.34",
  • "alert_threshold": "15.00"
}

Recharge Success Webhook

Triggered when an auto-recharge is successful.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

falls_below
required
string

The currently configured auto-recharge threshold (in USD).

recharge_to
required
string

The currently configured auto-recharge amount (in USD).

required
object

Payment details related to this auto-recharge event.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.recharge.success",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "falls_below": "5.00",
  • "recharge_to": "25.00",
  • "payment": {
    }
}

Recharge Failure Webhook

Triggered when an auto-recharge attempt fails.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

falls_below
required
string

The currently configured auto-recharge threshold (in USD).

recharge_to
required
string

The currently configured auto-recharge amount (in USD).

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.recharge.failed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "falls_below": "5.00",
  • "recharge_to": "25.00"
}

Renewal Success Webhook

Triggered when your billing package is set to auto-renew, and the auto-renewal process completes successfully.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The plan object that was just renewed.

required
object

Payment details related to this plan auto-renewal event.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.renewal.success",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "plan": {
    },
  • "payment": {
    }
}

Renewal Failure Webhook

Triggered when your billing package is set to auto-renew, but the auto-renewal process attempt fails.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The plan object of the auto-renewal attempt.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.renewal.failed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "plan": {
    }
}

Card Expiration Webhook

Triggered when one of your credit cards is about to expire.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The payment source object that is expiring.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "expiring.card.alert",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "payment_source": {
    }
}

Plan Expiration Webhook

Triggered when your billing package is set to expire and auto-renewal is disabled.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The plan object that is expiring.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "expiring.plan.alert",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "plan": {
    }
}

Certificate Events

Webhook events triggered during certificate monitoring checks.

Expiration Trigger Webhook

Triggered when a certificate reaches one of the expiration alert thresholds set on the monitor's profile, once for each threshold (for example at 30, 15 and 5 days before it expires).

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

expiry_days
required
integer

Whole days until the certificate expires. It doesn't go below 0: a certificate that has expired reports 0.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.expiration.trigger",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "expiry_days": 14
}

Expiration Resolve Webhook

Triggered when an expiring certificate is renewed. This occurs when the expiration threshold was crossed and the certificate has changed, indicating a renewal.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

expiry_days
required
integer

Days until the renewed certificate expires.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.expiration.resolve",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "expiry_days": 90
}

Error Trigger Webhook

Triggered when new certificate errors are detected during a check. The errors array contains only the newly detected errors, while current_errors contains all currently active errors. Only the findings the monitor's profile alerts on are included, and a finding dismissed on the monitor is left out.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

required
Array of objects (webhook_cert_error)

The newly detected certificate errors that triggered this event.

required
Array of objects (webhook_cert_error)

All currently active certificate errors for this monitor.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.error.trigger",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "errors": [
    ],
  • "current_errors": [
    ]
}

Error Resolve Webhook

Triggered when previously detected certificate errors are resolved. The resolved_errors array contains the errors that were resolved, while current_errors contains any remaining active errors. Only the findings the monitor's profile alerts on are included, and a finding dismissed on the monitor is left out.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

required
Array of objects (webhook_cert_error)

The certificate errors that have been resolved.

required
Array of objects (webhook_cert_error)

All currently active certificate errors for this monitor. This will be empty if all errors have been resolved.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.error.resolve",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "resolved_errors": [
    ],
  • "current_errors": [
    ]
}

Certificate Changed Webhook

Triggered when the monitor's certificate changes (its SHA-256 fingerprint differs from the one last alerted on), including a renewal, when the monitor's profile alerts on certificate changes. When a renewal brings the certificate out of its expiration warning while other errors remain, the event carries expiry_resolved: true (a renewal that clears everything also sends cert.expiration.resolve). Changes while the certificate is flapping are reported by cert.flapping instead.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

previous_fingerprint
required
string

The SHA-256 fingerprint of the previous certificate.

expiry_resolved
boolean

Present, and true, when the change is a renewal that ended the certificate's expiration warning while other errors remain.

new_fingerprint
required
string

The SHA-256 fingerprint of the new certificate.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.changed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "previous_fingerprint": "SHA256:2b:4d:8e:6a:1c:3f:9d:7e:5a:0b:8c:2d:4f:6e:1a:3b:9c:7d:5e:0a:8b:2c:4d:6f:1e:3a:9b:7c:5d:0e:8a:2b",
  • "expiry_resolved": true,
  • "new_fingerprint": "SHA256:9f:3a:7c:1e:5b:8d:2f:6a:4c:0e:9b:3d:7f:1a:5c:8e:2b:6d:4f:0a:9c:3e:7b:1d:5f:8a:2c:6e:4b:0d:9a:3f"
}

Flapping Detected Webhook

Triggered when the monitor's certificate keeps changing between checks: it changed at least three times over the monitor's last five checks that read a certificate, usually because the addresses or nodes behind the hostname serve different certificates. Sent once per episode, when the monitor's profile alerts on certificate flapping; while it lasts, certificate changes aren't sent, and an expiration threshold reached meanwhile is sent once it's over.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

flap_count
required
integer

How many times the certificate changed over the monitor's last five checks that read one.

stable_fingerprint
required
string

The SHA-256 fingerprint of the certificate last alerted on for this monitor.

alt_fingerprint
required
string

The SHA-256 fingerprint of the other certificate the latest check read.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.flapping",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "flap_count": 3,
  • "stable_fingerprint": "SHA256:2b:4d:8e:6a:1c:3f:9d:7e:5a:0b:8c:2d:4f:6e:1a:3b:9c:7d:5e:0a:8b:2c:4d:6f:1e:3a:9b:7c:5d:0e:8a:2b",
  • "alt_fingerprint": "SHA256:9f:3a:7c:1e:5b:8d:2f:6a:4c:0e:9b:3d:7f:1a:5c:8e:2b:6d:4f:0a:9c:3e:7b:1d:5f:8a:2c:6e:4b:0d:9a:3f"
}

Flapping Resolved Webhook

Triggered when a monitor that was flapping has read the same certificate on its last three checks, after a cert.flapping event was sent for it.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

stable_fingerprint
required
string

The SHA-256 fingerprint of the certificate the last three checks all read.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.flapping.resolve",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "stable_fingerprint": "SHA256:2b:4d:8e:6a:1c:3f:9d:7e:5a:0b:8c:2d:4f:6e:1a:3b:9c:7d:5e:0a:8b:2c:4d:6f:1e:3a:9b:7c:5d:0e:8a:2b"
}

Agent Events

Webhook events triggered for monitoring agent timeout and recovery.

Agent Timeout Webhook

Triggered when a persistent monitoring agent instance stops checking in beyond its configured timeout threshold. This event fires only when all persistent instances of the agent have timed out and there are newly timed-out instances to report.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The monitoring agent that triggered this event.

required
Array of objects (webhook_agent_instance)

The agent instances that have newly timed out. Only includes instances that have not been previously reported.

timeout_minutes
required
integer

The configured timeout threshold in minutes.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "agent.timeout",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "agent": {
    },
  • "instances": [
    ],
  • "timeout_minutes": 15
}

Agent Timeout Resolve Webhook

Triggered when a monitoring agent instance that had timed out resumes checking in. This event fires when at least one persistent instance recovers and the agent was previously in an alerted state.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The monitoring agent that triggered this event.

required
Array of objects (webhook_agent_instance)

The agent instances that have recovered and resumed checking in.

timeout_minutes
required
integer

The configured timeout threshold in minutes.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "agent.timeout.resolve",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "agent": {
    },
  • "instances": [
    ],
  • "timeout_minutes": 15
}