Discovery is the pipeline that finds certificates across your estate and stages them for import into your managed inventory. A scan targets one or more scanner types; results land as discovered certificates that you can review and selectively import. The exhaustive endpoint list is at API Reference. This page covers the shape of the API — authentication, pagination, and the discovery-specific request and response patterns.

​
Scanner types

TypeWhere it runsTypical targets
internal_ipAgentCIDR ranges
internal_dnsAgentDomains, DNS zones
k8s_secretsAgentNamespaces
ssh_authorized_keysAgentHost paths
ssh_pub_filesAgentHost paths
filesystemAgentDirectories
cloud_vaultAgentVault paths, cloud KMS namespaces
ca_certsCloud discoveryCA IDs
public_websitesCloud discoveryHostnames
Agent-scoped types require an agentId on the scan. Cloud-discovery types run from the control plane without an agent.

​
Creating a scan

​
name
string
required
​
types
string[]
Multi-scanner run. The platform dispatches each type to the appropriate executor.
​
targets
string[]
Targets appropriate to each scanner type (CIDRs, hostnames, namespaces, paths).
​
agentId
string
Required when any requested type is agent-scoped.
​
config
object
Scanner-specific options (ports, timeout, etc.).
curl -X POST https://api.tigertrust.example.com/api/discovery/scans \
  -H "X-API-Key: ck_9f2a...7c4e" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DC1 quarterly sweep",
    "types": ["internal_ip", "k8s_secrets"],
    "targets": ["10.20.0.0/16", "prod", "staging"],
    "agentId": "agent-dc1-01",
    "config": { "ports": [443, 8443, 9443] }
  }'

{
  "data": {
    "id": 4271,
    "name": "DC1 quarterly sweep",
    "status": "pending",
    "progress": 0,
    "createdAt": "2026-08-25T14:22:03.812Z"
  }
}

​
Scan lifecycle

A scan moves through these statuses:
StatusMeaning
pendingCreated, not yet started
runningDispatched to executors
completedAll executors finished
failedStopped or errored
Start a scan with a separate start call after creation. Stop it at any time to cancel; results already collected are preserved.

​
Scheduling

Attach a cron schedule to a scan to make it recur automatically. A 5- or 6-field cron expression is accepted (for example, 0 2 * * * for daily at 02:00 UTC). Set scheduleEnabled: false to pause without removing the schedule. Aliased scheduled-scan endpoints let you create, list, update, and delete recurring scans as a unit.

​
Reviewing results

After a scan completes, results are staged as discovered certificates — not yet in your managed inventory. Each discovered certificate carries the parsed subject, SANs, expiry, source (endpoint, port, Kubernetes secret name, filesystem path), and an imported flag. Filter by scan ID and import status to review only what you haven’t acted on yet.

​
Importing discovered certificates

POST /api/discovery/import promotes selected discovered certificates into your managed inventory. Import is idempotent by fingerprint — re-importing an existing certificate is a no-op.
​
certificateIds
integer[]
required
IDs from the discovered certificates list.
{
  "data": {
    "message": "Successfully imported 12 certificates",
    "imported": [
      { "id": 5183, "commonName": "api-internal.example.com" },
      { "id": 5184, "commonName": "kibana.example.com" }
    ]
  }
}

​
See also