Skip to main content

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

An audit is a single offensive engagement against the targets in a workspace. See Audit Modes for the conceptual overview.

​
Create an audit

POST /api/workspaces/{workspaceId}/audits Body 
{
  "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"
}
FieldTypeRequiredDescription
typestringyesshallow, deep, or autonomous
targetsstring[]yesOne or more target domains/subdomains
scopestringonly for autonomousFreeform mission brief injected into the agent prompt
callbackUrlstringnoURL to POST a completion event to
Response (201) 
{
  "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
ParamDescription
pagePage number (default: 1)
limitItems per page (default: 10, max: 50)
statusFilter by status: queued, running, completed, failed
typeFilter by audit type
Response (200) 
{
  "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) 
{
  "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) 
{
  "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) 
{
  "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) 
{
  "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) 
{
  "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: 
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).