OpenAPI Specification

HarborGuard publishes a hand-written OpenAPI 3.1 description of the public REST API. Use it to generate clients, drive contract tests, or import into Postman / Insomnia.

Download

The spec is served as a static asset:

Download harborguard-v1.yaml

curl https://harborguard.co/openapi/harborguard-v1.yaml -o harborguard-v1.yaml

Importing

Postman

1. Open Postman and click Import.
2. Choose Link and paste https://harborguard.co/openapi/harborguard-v1.yaml.
3. Postman creates a collection with one folder per resource tag. Add an Authorization → Bearer Token at the collection level using your API key (hg_ak_...) or PAT (hg_pat_...).

Insomnia

1. Application menu → Import and select From URL.
2. Paste the YAML URL above. Insomnia generates a Document and a Request Collection.
3. Set the bearer security scheme value in the environment.

Generated clients

Any OpenAPI 3.1 generator works. For example with openapi-typescript:

npx openapi-typescript https://harborguard.co/openapi/harborguard-v1.yaml -o ./harborguard.d.ts

What's covered

The spec describes the same endpoints documented in the Endpoints pages:

• Scans — list, create, get, status, delete, sensor upload
• Images — list with filters
• Registries — full CRUD plus test-connection, sync, sensor-status, schedule-scans
• Reports — list, generate, get, delete, artifact, download, regenerate, share, compliance pack, plus the read-time convenience endpoints (compliance, executive, posture, sla, sla/entries, technical)
• Vulnerabilities — list, distinct values, triage update
• Attestations — list, create, get, delete
• CVE Watch — alerts, settings, manual trigger
• Notification channels — full CRUD plus test and delivery history

Each operation declares an operationId, tags, parameters and request/response schemas, plus two HarborGuard-specific extensions:

What's NOT covered

Several internal or out-of-scope areas are intentionally omitted:

• Admin endpoints — /api/audit-log, /api/members, /api/teams, /api/roles, /api/sso/*, /api/api-keys, /api/personal-access-tokens, /api/organization/*. These are tied to the dashboard UI and may change without notice.
• Billing webhooks — /api/billing/webhook is a Stripe-signed inbound webhook, not a public client API.
• Sensor agent endpoints — /api/agent/* is an internal contract between the control plane and HarborGuard sensors. It is versioned and supported separately; do not call it from third-party tooling.
• Internal discovery routes — /api/health, /api/config, /api/search, /api/events, /api/test.

If you need automation against any of the above, contact support@harborguard.co — most use cases have a public-API equivalent.

Versioning policy

The spec is published at /openapi/harborguard-v1.yaml. We follow these rules:

• Additive (non-breaking) changes — new endpoints, new optional fields, new enum values that do not narrow existing ones — are appended to the v1 file. The info.version is bumped (e.g. 1.2.0 → 1.3.0).
• Breaking changes are published at a new path: /openapi/harborguard-v2.yaml. The previous version stays online for at least 12 months after a deprecation announcement.
• The info.version in this spec corresponds to the OpenAPI document, not the underlying HarborGuard release. The HTTP API itself is unversioned at the URL level.