Assessments API

Create and manage security assessments.

List Assessments

GET /api/v1/assessments

Returns security assessments for the authenticated organization.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Maximum results (1-200)
offset	integer	0	Pagination offset
type	string	-	Filter by type: vulnerability_scan, pentest, config_review, code_review
status	string	-	Filter: pending, in_progress, completed, failed

Example Request

curl "https://api.clawgrc.com/api/v1/assessments?status=completed&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "assessments": [
    {
      "id": "assess-uuid",
      "org_id": "org-uuid",
      "type": "vulnerability_scan",
      "status": "completed",
      "scope": {
        "targets": ["https://api.example.com"],
        "scan_type": "dast"
      },
      "configuration": {},
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:05:23Z",
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:05:23Z"
    }
  ],
  "total": 15,
  "limit": 10,
  "offset": 0
}

---

Create Assessment

POST /api/v1/assessments

Create a new security assessment.

Request Body

Field	Type	Required	Description
type	string	Yes	Assessment type
scope	object	No	What to assess (targets, systems, etc.)
configuration	object	No	Assessment-specific settings

Example Request

curl -X POST https://api.clawgrc.com/api/v1/assessments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "vulnerability_scan",
    "scope": {
      "targets": ["https://api.example.com"],
      "scan_type": "dast"
    }
  }'

Example Response (201 Created)

{
  "id": "assess-uuid",
  "type": "vulnerability_scan",
  "status": "pending",
  "created_at": "2025-01-15T14:30:00Z"
}

---

Get Assessment

GET /api/v1/assessments/:id

Returns a single assessment with its findings summary.

Error Responses

Status	Description
404	Assessment not found