Scans

A scan represents a single execution of the HarborGuard scanner pipeline against one container image tag. Scans are queued asynchronously and complete with vulnerability findings, an SBOM, package list, layer breakdown, and a compliance grade.

Base path: /api/scans

Method	Path	Min role	Rate limit
GET	`/api/scans`	`developer`	—
POST	`/api/scans`	`developer`	10 / min
GET	`/api/scans/{scanId}`	viewer (any)	—
GET	`/api/scans/{scanId}/status`	viewer (any)	—
DELETE	`/api/scans/{scanId}`	`admin`	—
POST	`/api/scans/upload`	API key only	—

The POST /api/scans/upload endpoint is used by HarborGuard sensors deployed inside customer networks to deliver scan envelopes to the control plane. Requires an API key (sensor-scoped); session and PAT auth are rejected. See Sensors for setup.

GET

/scans

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Query Parameters

`page`integer

Page number (1-indexed)

Default: 1Minimum: 1

`limit`integer

Page size (1–200)

Default: 50Minimum: 1Maximum: 200

`sort`string

Sort spec, e.g. scannedAt:desc. Sortable: scannedAt, status, compliance, riskScore.

`status`string

Value in: "QUEUED" | "IN_PROGRESS" | "COMPLETE" | "FAILED" | "CANCELLED"

`search`string

curl -X GET "https://harborguard.co/api/scans?page=1&limit=50&sort=string&status=QUEUED&search=string" \
  -H "X-API-Key: <token>"

{
  "data": [
    {
      "id": "scn-3kp9q1",
      "tagId": "tag-abc",
      "status": "COMPLETE",
      "compliance": "B",
      "riskScore": 47,
      "duration": 38211,
      "scannedAt": "2026-04-26T14:22:11.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "total": 142,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  },
  "links": {
    "self": "/api/scans?page=1&limit=50",
    "next": "/api/scans?page=2&limit=50"
  }
}

POST

/scans

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Request Body

application/jsonRequired

`body`
Required
object | object

curl -X POST "https://harborguard.co/api/scans" \
  -H "X-API-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "ghcr.io/acme/api:1.4.7",
    "scanners": [
      "trivy"
    ]
  }'

Accepted (all scans queued)

{
  "scanId": "scn-3kp9q1",
  "status": "QUEUED",
  "message": "Scan queued for execution",
  "url": "/dashboard/scans/scn-3kp9q1"
}

GET

/scans/{scanId}

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Path Parameters

`scanId`
Required
string

curl -X GET "https://harborguard.co/api/scans/string" \
  -H "X-API-Key: <token>"

{
  "data": {
    "id": "string",
    "image": {
      "name": "string",
      "tag": "string",
      "digest": "string"
    },
    "status": "QUEUED",
    "compliance": "A",
    "riskScore": 0,
    "scannedAt": "2019-08-24T14:15:22Z",
    "duration": 0,
    "vulnerabilities": [
      {
        "id": "string",
        "scanId": "string",
        "cveId": "CVE-2024-12345",
        "severity": "CRITICAL",
        "cvss": 0,
        "package": "string",
        "version": "string",
        "fixedVersion": "string",
        "scanner": "trivy",
        "triage": {
          "status": "OPEN",
          "assignee": "string",
          "slaDeadline": "2019-08-24T14:15:22Z",
          "note": "string",
          "updatedBy": "string",
          "updatedAt": "2019-08-24T14:15:22Z"
        },
        "timeline": {
          "detectedAt": "2019-08-24T14:15:22Z",
          "firstSeenAt": "2019-08-24T14:15:22Z",
          "resolvedAt": "2019-08-24T14:15:22Z"
        }
      }
    ],
    "packages": [
      {}
    ],
    "layers": [
      {}
    ]
  }
}

GET

/scans/{scanId}/status

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Path Parameters

`scanId`
Required
string

curl -X GET "https://harborguard.co/api/scans/string/status" \
  -H "X-API-Key: <token>"

DELETE

/scans/{scanId}

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Path Parameters

`scanId`
Required
string

curl -X DELETE "https://harborguard.co/api/scans/string" \
  -H "X-API-Key: <token>"

POST

/scans/upload

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

Request Body

application/jsonRequired

`[key: string]`any

`scan`object

`image`object

`scanners`array<object>

`vulnerabilities`array<object>

`packages`array<object>

`layers`array<object>

curl -X POST "https://harborguard.co/api/scans/upload" \
  -H "X-API-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scan": {
      "id": "string"
    },
    "image": {},
    "scanners": [
      {}
    ],
    "vulnerabilities": [
      {}
    ],
    "packages": [
      {}
    ],
    "layers": [
      {}
    ]
  }'

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

pageinteger

limitinteger

sortstring

statusstring

searchstring

Response

TypeScript

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

bodyRequiredobject | object

Object 1

Object 2

Response

TypeScript

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

scanIdRequiredstring

Response

TypeScript

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

scanIdRequiredstring

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

scanIdRequiredstring

X-API-Key<token>

AuthorizationRequiredBearer <token>

[key: string]any

scanobject

Attributes

imageobject

Attributes

scannersarray<object>

Object 1

vulnerabilitiesarray<object>

Object 1

packagesarray<object>

Object 1

layersarray<object>

Object 1

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`page`integer

`limit`integer

`sort`string

`status`string

`search`string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`body`
Required
object | object

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`scanId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`scanId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`scanId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`[key: string]`any

`scan`object

`image`object

`scanners`array<object>

`vulnerabilities`array<object>

`packages`array<object>

`layers`array<object>