GuardHound REST API

All endpoints require an API key (Authorization: Bearer ghk_…) or an authenticated session cookie. The full machine-readable schema lives at /api/docs (OpenAPI, dev environment). The summary below covers the resources most callers reach for; bulk import and exports are gated on the Pro, Business, and Agency plans.

Resource overview

Bulk import

Both endpoints accept either Content-Type: text/csv with the raw CSV body or Content-Type: application/json with { "csv": "...", "dryRun": false }. Pass ?dryRun=1 to preview without writing.

POST/api/v1/import/domains Pro+

Onboard your domain inventory in one shot. Idempotent on (account, domain).

POST/api/v1/import/monitors Pro+

Create up to your plan's monitor cap from a single CSV. Supports legacy domain monitors as well as HTTP, keyword, and ping uptime monitors mixed in the same upload. Idempotent on (account, domain) for legacy monitors and (account, kind, name) for service monitors.

CSV columns (header row required):

Pass ?dryRun=1 (or "dryRun": true in the JSON body) to preview the parse result without writing anything.

Re-uploading the same CSV is safe: imports are idempotent on (account, domain). Already-existing monitors are returned in the skippedDuplicate count instead of being recreated.

Sample request

curl -X POST https://guardhound.io/api/v1/import/monitors \
  -H "Authorization: Bearer ghk_live_…" \
  -H "Content-Type: text/csv" \
  --data-binary $'domain,email,label\nexample.com,ops@example.com,Marketing site\napi.example.com,,API gateway'

Sample response

{
  "created": 2,
  "skippedDuplicate": 0,
  "skippedForLimit": 0,
  "createdIds": ["…uuid…", "…uuid…"],
  "invalidRows": [],
  "planLimit": 10
}

Exports

All export endpoints stream a downloadable file with Content-Disposition: attachment. CSVs are RFC-4180 quoted; JSON bundles are pretty-printed.

GET/api/v1/exports/incidents.csv Pro+

Every incident on your account, including resolution timestamps, severity, and the monitor that triggered it. Optional ?since=ISO8601 filter.

GET/api/v1/exports/monitors.csv Pro+

Unified inventory across both legacy domain monitors and typed service monitors (HTTP / keyword / ping / etc.). Each row has a source column (legacy or service) so a single CSV gives you the full monitor footprint. Streamed in 1,000-row pages so multi-tenant accounts with hundreds of thousands of monitors download without timing out.

GET/api/v1/exports/scan-history.csv Pro+

Last 90 days of scan results across all monitors. Optional ?monitorId=… to scope to a single monitor and ?days=N (max 365) to widen the window.

GET/api/v1/exports/domains/:id.json Pro+

Per-domain JSON bundle: domain metadata, every monitor attached to it, the 90-day risk-score trendline (one row per monitor per day), and recent incidents. Designed for sharing a single domain's posture with auditors or customers. Per-finding detail (raw certificate observations, lookalike candidates) is intentionally excluded from this bundle — fetch those from their dedicated endpoints.

Risk trendline & explainability

GET/api/monitors/:id/risk-trend?days=90

Returns one daily point per snapshot with the headline score, label, an eight-dimension breakdown (availability, certificate hygiene, DNS / email auth, brand & phishing, asset exposure, vulnerability / web risk, change risk, hosting reputation), and the top three contributing finding categories for that day. Available on every plan that has at least one monitor; the snapshot cron writes one row per active monitor per day at 03:30 UTC.

The topContributors array is what powers the dashboard's "what changed since last week?" panel — each tuple contains a category (e.g. ssl, dns, cve), a severity, and an integer weight.

Errors

Need a SOC2 evidence pack, SIEM webhook, or scheduled export to S3? Email us — these are all on the Agency roadmap.