> ## Documentation Index
> Fetch the complete documentation index at: https://how.to.usegolem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audits API

> Launch audits, poll status, and retrieve findings and reports

# Audits API

## Launch an audit

`POST /api/apps/{appId}/audits`

```bash theme={null}
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:

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

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

See [Security Score](/audits/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](/audits/findings).

## Retrieve the report

`GET /api/apps/{appId}/audits/{auditId}/report`

Returns a short-lived presigned URL to the stored Markdown report:

```json theme={null}
{
  "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           |