Evidence API

Manage evidence artifacts that demonstrate control implementation.

List Evidence

GET /api/v1/evidence

Returns evidence artifacts for the authenticated organization.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Maximum results (1-200)
offset	integer	0	Pagination offset
status	string	-	Filter: pending, validated, rejected
source_type	string	-	Filter: screenshot, document, api_export, log, configuration
requirement_id	UUID	-	Filter by evidence requirement

Example Request

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

Example Response

{
  "evidence": [
    {
      "id": "ev-uuid",
      "org_id": "org-uuid",
      "requirement_id": "req-uuid",
      "source_type": "screenshot",
      "source_identifier": "AWS IAM MFA Policy - Production",
      "storage_path": "evidence/org-uuid/ev-uuid/iam-mfa.png",
      "file_hash": "sha256:a1b2c3d4e5f6...",
      "collected_at": "2025-01-10T10:00:00Z",
      "validated_at": "2025-01-10T14:00:00Z",
      "status": "validated",
      "metadata": {
        "aws_account": "123456789012",
        "region": "us-east-1"
      },
      "created_at": "2025-01-10T10:00:00Z",
      "updated_at": "2025-01-10T14:00:00Z"
    }
  ],
  "total": 245,
  "limit": 10,
  "offset": 0
}

---

Create Evidence

POST /api/v1/evidence

Upload a new evidence artifact.

Request Body

Field	Type	Required	Description
source_type	string	Yes	screenshot, document, api_export, log, configuration, certificate, report
source_identifier	string	Yes	Human-readable label for the artifact
requirement_id	UUID	No	Link to an evidence requirement
storage_path	string	No	Storage path for the uploaded file
file_hash	string	No	SHA-256 hash of the file content
collected_at	datetime	No	When the evidence was collected (defaults to now)
metadata	object	No	Arbitrary metadata

Example Request

curl -X POST https://api.clawgrc.com/api/v1/evidence \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "screenshot",
    "source_identifier": "AWS IAM MFA Policy - Production",
    "requirement_id": "req-uuid-here",
    "metadata": {
      "aws_account": "123456789012",
      "region": "us-east-1"
    }
  }'

Example Response (201 Created)

{
  "id": "ev-uuid",
  "org_id": "org-uuid",
  "source_type": "screenshot",
  "source_identifier": "AWS IAM MFA Policy - Production",
  "status": "pending",
  "created_at": "2025-01-15T14:30:00Z"
}

---

Get Evidence

GET /api/v1/evidence/:id

Returns a single evidence artifact by ID.

Error Responses

Status	Description
404	Evidence artifact not found

---

Update Evidence

PUT /api/v1/evidence/:id

Update evidence metadata or status. Used for validating or rejecting evidence.

Request Body

Field	Type	Description
status	string	pending, validated, or rejected
source_identifier	string	Update the label
metadata	object	Update metadata

Example Request

curl -X PUT https://api.clawgrc.com/api/v1/evidence/ev-uuid \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "validated"
  }'

---

Delete Evidence (Soft Delete)

DELETE /api/v1/evidence/:id

Soft-deletes an evidence artifact. Sets deleted_at timestamp but preserves the record for audit trail integrity.

Example Request

curl -X DELETE https://api.clawgrc.com/api/v1/evidence/ev-uuid \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (204 No Content)

No body returned.