TLS Check API

API reference

TLS Check HTTP endpoints on api.syndaq.com.

All TLS Check endpoints are served from https://api.syndaq.com/v1/tls/.

Authenticated requests require a valid TLS Check key. Lookup routes require your tl_sec_ secret key.

Endpoints overview

Method	Path	Auth	Purpose
GET	`/v1/tls/lookup`	Secret key	Lookup by `?host=` query parameter
GET	`/v1/tls/lookup/{host}`	Secret key	Lookup by hostname in the URL path
GET	`/v1/tls/status`	Public or secret key	Plan limits and quota snapshot

Response headers

Successful and error responses may include:

Header	Description
`X-Request-Id`	Unique ID for support and log correlation
`X-RateLimit-Limit`	Plan requests per minute for this key
`X-RateLimit-Remaining`	Requests left in the current minute window
`X-RateLimit-Reset`	Unix timestamp when the minute window resets
`X-Quota-Limit`	Monthly quota for the subscription
`X-Quota-Remaining`	Lookups left this calendar month (UTC)
`X-Quota-Period`	Current quota month (`YYYY-MM`)
`Retry-After`	Seconds to wait after HTTP 429

GET /v1/tls/lookup

Returns certificate metadata for a public hostname.

Request

Pass the target host using one of these forms:

GET /v1/tls/lookup/example.com
GET /v1/tls/lookup?host=example.com

You may omit https:// and path segments. Port defaults to 443 when not specified.

Headers:

Authorization: Bearer tl_sec_YOUR_SECRET_KEY

v1 scope

v1 returns hostname certificate metadata (validity window, issuer/subject, SANs, protocol, fingerprint). It is not a full cipher-suite audit, vulnerability scan, or certificate transparency search.

Success response (200)

{
  "success": true,
  "host": "example.com",
  "port": 443,
  "cached": true,
  "valid": true,
  "issuer": "DigiCert Inc",
  "subject": "example.com",
  "not_before": "2025-01-15T00:00:00Z",
  "not_after": "2026-02-15T23:59:59Z",
  "days_remaining": 215,
  "san": ["example.com", "www.example.com"],
  "protocol": "TLSv1.3",
  "fingerprint_sha256": "a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef",
  "request_id": "e6d04020be9b57b1e1069d6e483c0443"
}

Response fields

Field	Type	Description
`host`	string	Normalized hostname that was checked
`port`	integer	TLS port used for the check
`cached`	boolean	`true` when Syndaq already holds a recent result for this lookup
`valid`	boolean	Whether the presented certificate is currently within its validity window
`issuer`	string	Certificate issuer summary
`subject`	string	Certificate subject summary
`not_before`	string	Certificate not-before timestamp
`not_after`	string	Certificate not-after timestamp
`days_remaining`	integer	Days until expiry (may be negative if expired)
`san`	array	Subject Alternative Name hostnames
`protocol`	string	Negotiated TLS protocol when available
`fingerprint_sha256`	string	SHA-256 fingerprint of the certificate

GET /v1/tls/status

Returns key status, plan limits, and quota usage without performing a lookup.

Request

GET /v1/tls/status
Authorization: Bearer tl_sec_YOUR_SECRET_KEY

The public key (tl_pub_) is accepted on this route.

Success response (200)

{
  "success": true,
  "status": "active",
  "product": "tls",
  "plan": "starter",
  "rate_limit_per_minute": 60,
  "monthly_quota": 5000,
  "quota_unlimited": false,
  "quota_remaining": 4920,
  "quota_period": "2026-07"
}

Errors

Failed requests return JSON with success: false, error, error_code, and usually request_id.

HTTP	error_code	Typical cause
400	`invalid_host`	Missing or malformed hostname
401	`missing_credentials`	No API key provided
401	`invalid_api_key`	Unknown, inactive, or revoked key
401	`wrong_key_type`	Public key used on a lookup endpoint
403	`ip_not_allowed`	Caller IP not on the key allowlist
422	`host_not_allowed`	Private, reserved, or non-routable target
429	`rate_limit_exceeded`	Per-minute limit exceeded
429	`quota_exceeded`	Monthly quota exhausted
502	`lookup_failed`	Temporary TLS check failure
500	`internal_error`	Unexpected server error

Handle non-200 responses in your application and retry transient errors with exponential backoff.