API Reference

HarborGuard exposes a JSON REST API under the /api prefix. Every endpoint is scoped to the calling principal's organization and protected by one of three credential types described in Authentication.

A machine-readable description of every public endpoint is available as an OpenAPI 3.1 document at /openapi/harborguard-v1.yaml — see the OpenAPI spec page for download and import instructions.

Base URL

https://harborguard.co/api

Quickstart

Create an organization API key from Settings → API Keys, then issue a request:

curl https://harborguard.co/api/scans \
  -H "Authorization: Bearer hg_ak_..." \
  -H "Accept: application/json"

Or trigger a scan:

curl -X POST https://harborguard.co/api/scans \
  -H "Authorization: Bearer hg_ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image": "nginx:1.27",
    "scanners": ["trivy", "grype", "syft"]
  }'

Response envelope

Every successful response is wrapped in a consistent envelope. Single-resource responses contain only data. Paginated list responses also include meta and links.

{
  "data": { "...": "..." },
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 312,
    "totalPages": 7,
    "hasNext": true,
    "hasPrev": false
  },
  "links": {
    "self": "/api/scans?page=1&limit=50",
    "next": "/api/scans?page=2&limit=50"
  }
}

Error responses use a separate envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "issues": [
      { "path": "image", "message": "Required" }
    ]
  }
}

See Errors for the full code list.

Endpoint catalog

Other endpoints (members, teams, notification channels, audit log, attestations, patches, sensors, SSO) follow the same conventions and are documented in their respective feature pages.

Conventions

• Requests and responses use application/json unless explicitly noted (e.g. report downloads return application/pdf, text/csv, or application/zip).
• Timestamps are ISO 8601 in UTC.
• Resource IDs are opaque strings; do not parse them.
• Resource creation returns 201 Created. Asynchronous work (scans, report generation) returns 202 Accepted with a status URL or polling endpoint.
• Read Pagination, Rate Limits, and Errors before building integrations.

Reference