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

# Audits

> Launch, monitor, and retrieve security audits

# Audits

An audit is a single offensive engagement against the targets in a workspace. See [Audit Modes](/audits/overview) for the conceptual overview.

***

## Create an audit

`POST /api/workspaces/{workspaceId}/audits`

**Body**

```json theme={null}
{
  "type": "deep",
  "targets": ["acme.example.com", "api.acme.example.com"],
  "scope": "Required only for type=autonomous — operator-defined mission brief",
  "callbackUrl": "https://your-app.com/webhooks/audit-complete"
}
```

| Field         | Type      | Required              | Description                                           |
| ------------- | --------- | --------------------- | ----------------------------------------------------- |
| `type`        | string    | yes                   | `shallow`, `deep`, or `autonomous`                    |
| `targets`     | string\[] | yes                   | One or more target domains/subdomains                 |
| `scope`       | string    | only for `autonomous` | Freeform mission brief injected into the agent prompt |
| `callbackUrl` | string    | no                    | URL to POST a completion event to                     |

**Response (201)**

```json theme={null}
{
  "success": true,
  "data": {
    "audit": {
      "id": "audit_abc123",
      "workspaceId": "ws_abc123",
      "status": "queued",
      "type": "deep",
      "domain": "acme.example.com",
      "targets": ["acme.example.com", "api.acme.example.com"],
      "createdAt": "2026-05-18T12:00:00.000Z"
    }
  }
}
```

***

## List audits

`GET /api/workspaces/{workspaceId}/audits`

**Query parameters**

| Param    | Description                                                  |
| -------- | ------------------------------------------------------------ |
| `page`   | Page number (default: 1)                                     |
| `limit`  | Items per page (default: 10, max: 50)                        |
| `status` | Filter by status: `queued`, `running`, `completed`, `failed` |
| `type`   | Filter by audit type                                         |

**Response (200)**

```json theme={null}
{
  "success": true,
  "data": {
    "audits": [
      {
        "id": "audit_abc123",
        "status": "completed",
        "type": "deep",
        "domain": "acme.example.com",
        "findingCount": 23,
        "score": 65,
        "grade": "D",
        "createdAt": "2026-05-18T12:00:00.000Z",
        "completedAt": "2026-05-18T14:02:00.000Z"
      }
    ],
    "pagination": {
      "total": 47,
      "limit": 10,
      "offset": 0,
      "hasMore": true
    }
  }
}
```

***

## Get an audit

`GET /api/workspaces/{workspaceId}/audits/{auditId}`

**Response (200)**

```json theme={null}
{
  "success": true,
  "data": {
    "audit": {
      "id": "audit_abc123",
      "status": "completed",
      "type": "deep",
      "domain": "acme.example.com",
      "targets": ["acme.example.com"],
      "findingCount": 23,
      "score": 65,
      "grade": "D",
      "severityBreakdown": {
        "critical": 1,
        "high": 2,
        "medium": 8,
        "low": 11,
        "informational": 1
      },
      "findings": [
        {
          "id": "finding_001",
          "severity": "critical",
          "category": "rce",
          "title": "Authenticated RCE via deserialization endpoint",
          "description": "POST /api/internal/jobs accepts Java-serialized payloads...",
          "evidence": "$ curl -X POST ... [full shell output] ...",
          "recommendation": "Disable Java deserialization on /api/internal/jobs...",
          "screenshotUrl": "https://...",
          "discoveredAt": "2026-05-18T13:14:22.000Z"
        }
      ],
      "createdAt": "2026-05-18T12:00:00.000Z",
      "startedAt": "2026-05-18T12:00:35.000Z",
      "completedAt": "2026-05-18T14:02:00.000Z"
    }
  }
}
```

***

## Get the structured report

Returns the report data — finding details, score breakdown, metadata — without the audit's full session state.

`GET /api/workspaces/{workspaceId}/audits/{auditId}/report`

**Response (200)**

```json theme={null}
{
  "success": true,
  "data": {
    "report": {
      "auditId": "audit_abc123",
      "domain": "acme.example.com",
      "summary": {
        "critical": 1,
        "high": 2,
        "medium": 8,
        "low": 11,
        "informational": 1
      },
      "score": 65,
      "grade": "D",
      "findings": [ ... ],
      "pdfUrl": "https://...",
      "generatedAt": "2026-05-18T14:02:00.000Z"
    }
  }
}
```

***

## Get the PDF report

Returns a presigned URL to the generated PDF.

`GET /api/workspaces/{workspaceId}/audits/{auditId}/pdf`

**Response (200)**

```json theme={null}
{
  "success": true,
  "data": {
    "pdfUrl": "https://s3.amazonaws.com/.../withgiga-audit-acme-2026-05-18.pdf?...&Expires=..."
  }
}
```

***

## Get the asciinema recording

`GET /api/workspaces/{workspaceId}/audits/{auditId}/recording`

**Response (200)**

```json theme={null}
{
  "success": true,
  "data": {
    "recordingUrl": "https://s3.amazonaws.com/.../audit_abc123.cast?...&Expires=..."
  }
}
```

Download and play with `asciinema play recording.cast`, or upload to asciinema.org.

***

## Cancel an audit

Stops a running audit immediately. Findings discovered before cancellation are preserved.

`POST /api/workspaces/{workspaceId}/audits/{auditId}/stop`

**Response (200)**

```json theme={null}
{
  "success": true,
  "message": "Audit stopped"
}
```

***

## Callback / webhook

If you provide a `callbackUrl` when creating the audit, WithGiga sends a POST to that URL when the audit completes or fails:

```json theme={null}
POST {callbackUrl}
Content-Type: application/json
X-Giga-Signature: sha256=...

{
  "auditId": "audit_abc123",
  "workspaceId": "ws_abc123",
  "status": "completed",
  "score": 65,
  "grade": "D",
  "findingCount": 23,
  "severityBreakdown": { "critical": 1, "high": 2, ... }
}
```

Verify the signature using your account's webhook signing secret (available in **Settings → Webhooks**).