Start a certificate check

POST

/api/v1/certificates/check

curl --request POST \
  --url https://app.hostrepute.com/api/v1/certificates/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "host": "mail.example.com", "protocol": "https", "port": 443, "sni": "mail.example.com", "callback_url": "https://hooks.example.com/hostrepute/scans" }'

Start checking the TLS certificate a host presents. The response comes back straight away with the check’s uuid and status; poll GET /api/v1/certificates/status/{scan_uuid} until is_completed is true or status is failed, or pass a callback_url to be told when it ends. Every IP address the host resolves to is checked.

Costs 1 credit. Needs the certificate:check ability.

Authorizations

• bearer

Request Body^required

Media typeapplication/json

object

host

required

The host name or IP address to check. A URL is accepted and its host name is used.

string

Example

mail.example.com

protocol

How to connect: https or tls for a direct TLS connection, or starttls_smtp, starttls_imap, starttls_pop3, starttls_ldap or starttls_ftp to upgrade a plain connection with STARTTLS. Defaults to https.

string

nullable

Allowed values: https tls starttls_smtp starttls_imap starttls_pop3 starttls_ldap starttls_ftp

Example

https

port

The port to connect to, from 1 to 65535. Defaults to the protocol’s usual port: 443 for https and tls, 25 for starttls_smtp, 143 for starttls_imap, 110 for starttls_pop3, 389 for starttls_ldap and 21 for starttls_ftp.

integer

nullable

Example

443

sni

The host name to send in the TLS Server Name Indication. Defaults to host.

string

nullable

Example

mail.example.com

callback_url

A public HTTPS URL that HostRepute sends a POST to when the check ends. The request carries the X-Webhook-Event (certificate.scan.completed), X-Webhook-Timestamp and X-Webhook-Signature-V3 headers, signed with your team’s webhook secret. Read https://docs.hostrepute.com/developers/webhooks/

string

nullable

Example

https://hooks.example.com/hostrepute/scans

Responses

201

Media typeapplication/json

object

data

object

uuid

string

host

string

port

integer

protocol

string

sni

string

nullable

status

string

is_completed

boolean

callback_status

string

nullable

started_at

string

nullable

completed_at

string

nullable

created_at

string

Example

{
  "data": {
    "uuid": "01a178db-d882-7223-aeac-dfab82daeffa",
    "host": "mail.example.com",
    "port": 443,
    "protocol": "https",
    "sni": null,
    "status": "pending",
    "is_completed": false,
    "callback_status": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-10-26T15:37:16.000000Z"
  }
}

402

Not enough credits

Media typeapplication/json

object

message

string

required_credits

integer

available_credits

integer

Example

{
  "message": "Insufficient credits.",
  "required_credits": 1,
  "available_credits": 0
}

422

Invalid input

Media typeapplication/json

object

message

string

errors

object

protocol

Array<string>

Example

{
  "message": "The protocol must be a supported certificate protocol.",
  "errors": {
    "protocol": [
      "The protocol must be a supported certificate protocol."
    ]
  }
}