Certificates API

Certificate monitoring checks the TLS certificate and chain of every outbound HTTPS host your API calls, about once a day. See Monitor the certificates of hosts you call for how it works in the app.

Plan: needs a plan that includes Certificate monitoring. Reading hosts and settings keeps working if the plan changes. Adding hosts counts toward the plan’s monitored host limit. Permissions: any member, or a user or administrator API token, can read hosts and re-check one. Adding, changing and removing hosts, and the reminders, need an owner or admin, or an administrator API token. A token with access scopes needs alerts:read to read and alerts:write for everything else, re-checks included.

Hosts are account-wide: one host’s certificate serves every bucket that calls it. Each host is a host:port pair.

The host object #

• sid (string, required): The monitored host’s identifier (tlsw_ followed by 27 letters and digits).

• host (string, required): The hostname.

• port (integer, required): The port, usually 443.

• source (string, required): How the host was added: auto (found in outbound calls) or manual (added by hand).

• status (string, required): active, paused, ignored, stale (no request in the last 30 days and not Always monitor) or limited (over the plan’s limit).

• alwaysMonitor (boolean, required): Checked even without requests.

• monitored (boolean, required): Whether the host is checked now: active with a request in the last 30 days, or Always monitor.

• bucketSids (string[], required): The buckets whose traffic called the host.

• environmentSids (string[], required): The environments whose traffic called it.

• firstSeenAt (string | null): When the host was first seen (ISO 8601).

• lastSeenAt (string | null): When it was last called. A host added by hand counts as called on the day it was added.

• vendor (object, required): name, contact (an email address, URL or phone number) and statusUrl, each a string or null. Included in alerts about the host.

• notes (string | null): Free text.

• certificate (object, required): The result of the last check.

properties

• checkStatus (string): pending (not checked yet), ok, expiring, expired, invalid or unreachable

• lastCheckedAt (string | null): When the host was last checked

• lastSuccessAt (string | null): When a check last read a certificate

• nextCheckAt (string | null): When the next check is due, while the host is monitored

• notBefore (string | null): The start of the certificate’s validity

• notAfter (string | null): When it expires

• daysRemaining (integer | null): Days until it expires

• subjectCn (string | null): The common name

• san (string[]): The other names it is valid for

• issuer (string | null): The issuer, with issuerCn and issuerOrg

• serial (string | null): The serial number

• fingerprintSha256 (string | null): The SHA-256 fingerprint. Hosts with the same fingerprint share a certificate

• keyType (string | null): The key type, with keyBits

• signatureAlgorithm (string | null): The signature algorithm

• tlsVersion (string | null): The TLS version negotiated

• chainValid (boolean | null): Whether a standard client trusts the chain

• hostnameMatch (boolean | null): Whether the certificate covers the hostname

• validationError (string | null): Why a client rejects the certificate, when it does

• chainCapture (string | null): handshake when the chain was read exactly as the server sent it, or reconstructed when the server only speaks TLS 1.3 and the chain was rebuilt

• chainStatus (string | null): complete, misordered, incomplete, wrong_intermediate, untrusted, expired_intermediate, expiring_intermediate, invalid_leaf or weak

• chainIssues (object[]): Each problem found: code (for example INCOMPLETE_CHAIN, WRONG_INTERMEDIATE, UNTRUSTED_ROOT, CHAIN_CERT_EXPIRING, WEAK_SIGNATURE, MISORDERED_CHAIN, ISSUER_CHANGED), severity and message

• chainNotAfter (string | null): When the first certificate in the chain expires, with chainDaysRemaining

• resolvedIp (string | null): The address that was checked

• consecutiveFailures (integer): Checks in a row that could not complete

• lastErrorCode (string | null): Why the last check failed, with lastError

• createdAt (string | null): When the host was added.

• updatedAt (string | null): When it last changed.

List hosts #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/certificates

Lists monitored hosts, soonest expiry first, up to 1,000. By default only monitored hosts are listed: those with a request in the last 30 days, or with Always monitor on.

Path parameters #

• accountSid (path, string, required): The account identifier.

Query parameters #

• status (query, string): One status, or several separated by commas: active, paused, ignored, stale, limited.

• checkStatus (query, string): pending, ok, expiring, expired, invalid or unreachable.

• chainStatus (query, string): One chain status, such as incomplete.

• chainIssues (query, boolean): Only hosts whose chain has a problem (anything but complete or merely out of order).

• expiresWithinDays (query, integer): Only certificates that expire within this many days (0 to 3650).

• alwaysMonitor (query, boolean): Only hosts with Always monitor on, or off.

• fingerprint (query, string): Only hosts serving the certificate with this SHA-256 fingerprint (64 hex characters).

• bucketSid (query, string): Only hosts this bucket called.

• q (query, string): Part of the hostname.

• includeUnmonitored (query, boolean, default false): Also list hosts without a request in 30 days that don’t have Always monitor on.

• groupBy (query, string): certificate: one record per certificate, each with fingerprintSha256, certificate and hosts (the host objects that serve it). Hosts not checked yet stand alone.

Response #

records, a list of host objects (or groups, with groupBy), and hasMore, which is true when more than 1,000 hosts match.

curl "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/certificates?expiresWithinDays=7" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

{
  "hasMore": false,
  "records": [
    {
      "sid": "tlsw_2kM4nP6qR8sT1uV3wX5yZ7aB9cE",
      "host": "api.acme-pay.example",
      "port": 443,
      "source": "auto",
      "status": "active",
      "alwaysMonitor": false,
      "monitored": true,
      "bucketSids": ["k3m9p2x"],
      "environmentSids": ["env_2pQ7rS9tU1vW3xY5zA7bC9dE1fG"],
      "firstSeenAt": "2026-09-14T08:12:40.000Z",
      "lastSeenAt": "2026-11-03T17:41:09.000Z",
      "vendor": { "name": "Acme Pay", "contact": "[email protected]", "statusUrl": null },
      "notes": null,
      "certificate": {
        "checkStatus": "expiring",
        "lastCheckedAt": "2026-11-04T06:02:13.000Z",
        "lastSuccessAt": "2026-11-04T06:02:13.000Z",
        "nextCheckAt": "2026-11-05T06:19:51.000Z",
        "notBefore": "2026-08-10T00:00:00.000Z",
        "notAfter": "2026-11-09T23:59:59.000Z",
        "daysRemaining": 5,
        "subjectCn": "api.acme-pay.example",
        "issuer": "CN=R11,O=Let's Encrypt,C=US",
        "issuerCn": "R11",
        "issuerOrg": "Let's Encrypt",
        "san": ["api.acme-pay.example"],
        "serial": "04a1c3f2e98b7d6c5b4a3f2e1d0c9b8a7f6e",
        "fingerprintSha256": "9f2c4e6a8b0d1f3e5a7c9b1d3f5e7a9c0b2d4f6e8a0c2e4f6a8b0d2c4e6f8a0b",
        "keyType": "EC",
        "keyBits": 256,
        "signatureAlgorithm": "sha256WithRSAEncryption",
        "tlsVersion": "TLSv1.3",
        "chainValid": true,
        "hostnameMatch": true,
        "validationError": null,
        "chainCapture": "handshake",
        "chainStatus": "complete",
        "chainIssues": [],
        "chainNotAfter": "2027-03-12T23:59:59.000Z",
        "chainDaysRemaining": 128,
        "resolvedIp": "203.0.113.24",
        "consecutiveFailures": 0,
        "lastErrorCode": null,
        "lastError": null
      },
      "createdAt": "2026-09-14T08:12:41.000Z",
      "updatedAt": "2026-11-04T06:02:13.000Z"
    }
  ]
}

Get host #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/certificates/{watchSid}

Path parameters #

• accountSid (path, string, required): The account identifier.

• watchSid (path, string, required): The host’s identifier.

Response #

The host object, with:

• chain: each certificate in the chain, from the server’s certificate up, with its subject, issuer, notAfter, keyType, keyBits, signatureAlgorithm, fingerprintSha256 and source: sent (by the server), downloaded or known_intermediate (not sent, so a client has to fetch it) or trust_store.
• chainPaths: the certification paths a client can build, when there is more than one (for example through a cross-signed root).
• history: a row each time the certificate, its chain or its status changed, newest first, up to 100: observedAt, fingerprintSha256, notBefore, notAfter, issuerCn, checkStatus, validationError, chainStatus and chainIssues.
• sharedWith: the account’s other hosts on the same certificate (sid, host, port), up to 100.

curl "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/certificates/tlsw_2kM4nP6qR8sT1uV3wX5yZ7aB9cE" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

Add host #

POST https://api.apitraffic.io/v1/accounts/{accountSid}/certificates

Adds a host by hand, to watch it before any traffic reaches it or to keep a rarely called vendor monitored. The host counts as called on the day it is added: it is monitored for 30 days, then only while it gets traffic, unless alwaysMonitor is on. Its first check runs within 15 minutes.

Path parameters #

• accountSid (path, string, required): The account identifier.

Body parameters #

• host (body, string, required): A public hostname, such as api.vendor.com, optionally with a port (api.vendor.com:8443). IP addresses and internal names are refused.

• port (body, integer, default 443): 443, 8443, 4443, 9443 or 10443. Other ports are added from your traffic on their own.

• alwaysMonitor (body, boolean, default false): Keep checking the host without requests.

• vendor (body, object): name, contact and statusUrl.

• notes (body, string): Up to 2,000 characters.

Response #

The new host object.

curl -X POST "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/certificates" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "host": "api.acme-freight.example", "alwaysMonitor": true, "vendor": { "name": "Acme Freight", "contact": "[email protected]" } }'

Update host #

PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/certificates/{watchSid}

Pauses, ignores or resumes a host, turns Always monitor on or off, or edits the vendor contact and notes. Send at least one field.

Path parameters #

• accountSid (path, string, required): The account identifier.

• watchSid (path, string, required): The host’s identifier.

Body parameters #

• status (body, string): paused stops checks and alerts. ignored does the same and keeps traffic from adding the host again. active resumes it. A host without a request in the last 30 days can only be resumed with alwaysMonitor on.

• alwaysMonitor (body, boolean): Keep checking the host without requests.

• vendor (body, object): name, contact and statusUrl.

• notes (body, string): Up to 2,000 characters.

Response #

The updated host object.

curl -X PATCH "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/certificates/tlsw_2kM4nP6qR8sT1uV3wX5yZ7aB9cE" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Remove host #

DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/certificates/{watchSid}

Stops tracking a host. A host found in traffic is added again by its traffic within the hour; to keep it out, set its status to ignored instead.

Path parameters #

• accountSid (path, string, required): The account identifier.

• watchSid (path, string, required): The host’s identifier.

Response #

{ "sid": "tlsw_...", "deleted": true }

curl -X DELETE "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/certificates/tlsw_2kM4nP6qR8sT1uV3wX5yZ7aB9cE" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

Re-check host #

POST https://api.apitraffic.io/v1/accounts/{accountSid}/certificates/{watchSid}/check

Checks the certificate now and waits up to 20 seconds for the result. Within 5 minutes of the host’s last check, the last result is returned instead. Only a monitored host can be re-checked.

Path parameters #

• accountSid (path, string, required): The account identifier.

• watchSid (path, string, required): The host’s identifier.

Response #

The host object, with the detail fields of Get host, and:

• rechecked: true when this call ran a fresh check.
• checkFailed: true when the check ran but the host could not be checked. The reason is in certificate.lastError.
• failed: true when the check could not run just now. The last result is returned.
• inProgress: true when a check is still running. The last result is returned.

curl -X POST "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/certificates/tlsw_2kM4nP6qR8sT1uV3wX5yZ7aB9cE/check" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

Get reminder settings #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/certificates/settings

Path parameters #

• accountSid (path, string, required): The account identifier.

Response #

• reminderDays (integer[], required): The early reminders turned on: any of 30 and 14.

• reminderOptions (integer[], required): The reminders you can choose: [30, 14].

• warningDays (integer, required): When the always-on warning fires: 7 days before expiry.

• criticalDays (integer, required): When the always-on critical alert fires: 1 day before expiry.

{ "reminderDays": [30, 14], "warningDays": 7, "criticalDays": 1, "reminderOptions": [30, 14] }

Update reminder settings #

PUT https://api.apitraffic.io/v1/accounts/{accountSid}/certificates/settings

Turns the 30-day and 14-day early reminders on or off. Reminders are info alerts, sent in the alert digest. The 7-day warning and the 1-day critical alert are always on.

Path parameters #

• accountSid (path, string, required): The account identifier.

Body parameters #

• reminderDays (body, integer[], required): Any of 30 and 14. An empty list turns both off.

Response #

The reminder settings, as Get reminder settings returns them.

curl -X PUT "https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/certificates/settings" \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reminderDays": [14] }'

Errors #

Events #

Adding, removing or changing a host, and changing the reminders, are recorded in the account’s activity and sent to webhooks as alerting.certificate_watch_changed and alerting.certificate_settings_changed. See the webhook event reference.