Submit a certificate check result

POST

/api/v1/certificate-agent/tasks/{monitor_uuid}/result

curl --request POST \
  --url https://app.hostrepute.com/api/v1/certificate-agent/tasks/01a178db-e1fb-708c-b49d-4d2e638817d7/result \
  --header 'Content-Type: application/json' \
  --data '{ "status": "pending", "host": "intranet.example.com", "port": 443, "protocol": "https", "sni": "intranet.example.com", "checked_ip": "192.0.2.40", "resolved_ips": [ "192.0.2.40" ], "issuer": "Northwind Internal CA", "subject": "CN=intranet.example.com", "common_name": "intranet.example.com", "sans": [ "intranet.example.com", "wiki.example.com" ], "serial_number": "4F1A9C2E7B3D5A60", "fingerprint_sha256": "3B7E1C5A9D2F4E6B8A0C1D3E5F7A9B2C4D6E8F0A1B3C5D7E9F1A2B4C6D8E0F2A", "signature_algorithm": "sha256WithRSAEncryption", "valid_from": "2026-08-01T00:00:00Z", "expires_at": "2026-12-10T23:59:59Z", "days_remaining": 45, "chain_valid": true, "hostname_valid": true, "caa_valid": true, "algorithm_secure": true, "revocation_status": "good", "events": [], "diagnostics": null, "error_message": null, "checked_at": "2026-10-26T15:37:18Z" }'

Send the result of a certificate check the agent ran. HostRepute grades the certificate, records the check, updates the certificate’s status and sends any alerts. host, port and protocol, when sent, must match the certificate being checked.

Authenticate with the agent’s token, Authorization: Bearer hrca_…, not a team API token.

Parameters

Path Parameters

monitor_uuid

required

string

The uuid of the check, from GET /api/v1/certificate-agent/tasks.

Example

01a178db-e1fb-708c-b49d-4d2e638817d7

Request Body^required

Media typeapplication/json

object

status

required

The certificate’s health as the agent saw it.

string

Allowed values: pending healthy expiring expired invalid failed

Example

healthy

host

The host name that was checked.

string

nullable

Example

intranet.example.com

port

The port that was checked, from 1 to 65535.

integer

nullable

Example

443

protocol

The protocol that was used.

string

nullable

Allowed values: https tls starttls_smtp starttls_imap starttls_pop3 starttls_ldap starttls_ftp

Example

https

sni

The Server Name Indication that was sent.

string

nullable

Example

intranet.example.com

checked_ip

The IP address the agent connected to.

string

nullable

Example

192.0.2.40

resolved_ips

Every IP address the host name resolved to, up to 25.

Array<string>

Example

[
  "192.0.2.40"
]

issuer

The certificate’s issuer.

string

nullable

Example

Northwind Internal CA

subject

The certificate’s subject.

string

nullable

Example

CN=intranet.example.com

common_name

The certificate’s common name.

string

nullable

Example

intranet.example.com

sans

The certificate’s subject alternative names, up to 100.

Array<string>

Example

[
  "intranet.example.com",
  "wiki.example.com"
]

serial_number

The certificate’s serial number.

string

nullable

Example

4F1A9C2E7B3D5A60

fingerprint_sha256

The SHA-256 fingerprint of the certificate.

string

nullable

Example

3B7E1C5A9D2F4E6B8A0C1D3E5F7A9B2C4D6E8F0A1B3C5D7E9F1A2B4C6D8E0F2A

signature_algorithm

The certificate’s signature algorithm.

string

nullable

Example

sha256WithRSAEncryption

valid_from

When the certificate became valid (ISO 8601).

string

nullable

Example

2026-08-01T00:00:00Z

expires_at

When the certificate expires (ISO 8601).

string

nullable

Example

2026-12-10T23:59:59Z

days_remaining

Days until the certificate expires.

integer

nullable

Example

45

chain_valid

Whether the certificate chain is trusted.

boolean

nullable

Example

true

hostname_valid

Whether the certificate covers the host name.

boolean

nullable

Example

true

caa_valid

Whether the domain’s CAA records allow the issuer.

boolean

nullable

Example

true

algorithm_secure

Whether the signature and key meet modern strength thresholds.

boolean

nullable

Example

true

revocation_status

The certificate’s revocation status: good, revoked or unknown.

string

nullable

Example

good

events

Certificate events the agent noticed, up to 20, from certificate_expiring, certificate_expired, certificate_recovered, hostname_mismatch, chain_invalid, certificate_revoked, connection_failed, fingerprint_changed, caa_missing_or_changed, algorithm_weak and load_balancer_drift. HostRepute also works out events itself by comparing with the last check.

Array<string>

Example

[]

diagnostics

Extra details for troubleshooting, up to 50 entries. They’re stored with the check.

object

Example

null

error_message

What went wrong, when the check failed. Up to 2,000 characters.

string

nullable

Example

null

checked_at

When the agent ran the check (ISO 8601).

string

nullable

Example

2026-10-26T15:37:18Z

Responses

201

Media typeapplication/json

object

data

object

uuid

string

status

string

certificate_grade

string

certificate_score

integer

events

array

checked_at

string

Example

{
  "data": {
    "uuid": "01a178db-e206-73cc-829e-4bf5f55fad0c",
    "status": "healthy",
    "certificate_grade": "A",
    "certificate_score": 100,
    "events": [],
    "checked_at": "2026-10-26T15:37:18.000000Z"
  }
}

401

Missing or invalid agent token

Media typeapplication/json

object

message

string

Example

{
  "message": "Invalid certificate agent token."
}

404

The check isn’t assigned to this agent

Media typeapplication/json

object

message

string

Example

{
  "message": "No query results for model [App\\Models\\CertificateMonitor] 01a178db-e1fb-708c-b49d-4d2e638817d7"
}

422

The result doesn’t match the check

Media typeapplication/json

object

message

string

errors

object

host

Array<string>

Example

{
  "message": "The result host must match the assigned certificate monitor.",
  "errors": {
    "host": [
      "The result host must match the assigned certificate monitor."
    ]
  }
}