Audits API

Launch an audit

POST /api/apps/{appId}/audits

curl -X POST https://api.usegolem.ai/api/apps/{appId}/audits \
  -H "Authorization: Bearer $GOLEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "deep"}'

Field	Required	Notes
`type`	yes	`shallow` or `deep` (`autonomous` is plan-gated)
`targets`	no	Subdomains to include; defaults to the app’s domain. Must be in scope.
`scope`	no	Mission brief for autonomous audits (~1,500 chars max)
`securityFocus`	no	Per-run override of the app’s focus areas
`onboarding`	no	Internal: first-audit reservation flow

The credits are reserved at launch. The response includes the created audit and the Trigger.dev run handle:

{
  "success": true,
  "data": {
    "audit": {
      "id": "68a...",
      "appId": "689...",
      "type": "deep",
      "status": "pending",
      "targets": ["acme.example.com"],
      "createdAt": "2026-09-09T12:00:00.000Z"
    },
    "run": {
      "runId": "run_...",
      "publicAccessToken": "..."
    }
  }
}

The publicAccessToken can be used to subscribe to live run updates via Trigger.dev realtime. If the app hasn’t accepted the authorized-testing terms yet, the launch fails — call POST /api/apps/{id}/accept-terms with the signed name first.

List audits

GET /api/apps/{appId}/audits?page=1&limit=20

{
  "success": true,
  "data": {
    "audits": [ ... ],
    "total": 14,
    "page": 1
  }
}

Get one audit

GET /api/apps/{appId}/audits/{auditId} Returns the full audit: status, score with breakdown, findings with evidence, and coverage summary.

Status values

pending → running → completed | partial | failed | cancelled

Score in the response

{
  "score": "C",
  "scoreNumeric": 62,
  "riskScoreNumeric": 71,
  "scoreBreakdown": {
    "startingScore": 100,
    "findingDeduction": 28.6,
    "riskScore": 71,
    "coverageCeiling": 62,
    "finalScore": 62,
    "contributions": [ ... ]
  }
}

See Security Score for how the numbers are computed.

Findings

Each finding includes severity, class, cwe, optional cve/cveScore/kev enrichment, source (agent | baseline | revalidation), verification status, structured evidence, and recommendation. See Findings & Evidence.

Retrieve the report

GET /api/apps/{appId}/audits/{auditId}/report Returns a short-lived presigned URL to the stored Markdown report:

{
  "success": true,
  "data": {
    "url": "https://s3.../report.md?...",
    "expiresIn": 600,
    "contentType": "text/markdown"
  }
}

Returns 404 "Report not available yet" until the audit finalizes. The URL expires after 10 minutes.

Manage an audit

Endpoint	Purpose
`PATCH /api/apps/{appId}/audits/{auditId}`	Update mutable audit fields
`DELETE /api/apps/{appId}/audits/{auditId}`	Soft-delete the audit
`POST /api/apps/{appId}/audits/{auditId}/findings/{findingId}/exploit`	Re-run exploit verification for a finding

Error reference

Error	Meaning
`Insufficient credits`	The app’s balance can’t cover this audit type
`Plan gate`	The audit type isn’t allowed on the app’s plan
`Targets out of scope`	A target isn’t within the app’s verified scope
`Audit not found`	Unknown ID or not yours
`Report not available yet`	The audit hasn’t finished finalizing

Getting Started

Audits

How It Works

Platform

Billing

API

Audits API

Audits API

Launch an audit

List audits

Get one audit

Status values

Score in the response

Findings

Retrieve the report

Manage an audit

Error reference

​Audits API

​Launch an audit

​List audits

​Get one audit

​Status values

​Score in the response

​Findings

​Retrieve the report

​Manage an audit

​Error reference

Audits API

Launch an audit

List audits

Get one audit

Status values

Score in the response

Findings

Retrieve the report

Manage an audit

Error reference