Evidence Collection API

Automated evidence vault — collect, track, and export compliance evidence from connected integrations. Includes drift detection, timeline views, and auditor-ready export packages. All endpoints require JWT authentication.

List Evidence Items

GET /api/v1/evidence 🔒

List all evidence items for the account, ordered by collection date (newest first).

Query Parameters

Param	Type	Description
`limit`	integer	Max results (default 50)
`offset`	integer	Pagination offset (default 0)

curl https://api.privabase.com/api/v1/evidence \
  -H "Authorization: Bearer YOUR_TOKEN"

// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/evidence', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const { data } = await res.json();

# Python
resp = requests.get('https://api.privabase.com/api/v1/evidence',
    headers={'Authorization': 'Bearer YOUR_TOKEN'})
evidence = resp.json()['data']

Response

{
  "success": true,
  "data": [
    {
      "id": "ev-abc-123",
      "control_id": "soc2-cc6.1",
      "framework_id": "soc2",
      "integration_id": "aws",
      "type": "config_check",
      "status": "passing",
      "title": "S3 bucket encryption enabled",
      "collected_at": "2026-03-14T10:30:00Z"
    }
  ]
}

Collection Runs

GET /api/v1/evidence/collections 🔒

List evidence collection runs. Optionally filter by integration or status.

Query Parameters

Param	Type	Description
`integration_id`	string	Filter by integration
`status`	string	Filter: `running`, `completed`, `failed`
`limit`	integer	Max results (default 50)
`offset`	integer	Pagination offset

curl "https://api.privabase.com/api/v1/evidence/collections?integration_id=aws" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/v1/evidence/collections/trigger 🔒

Manually trigger an evidence collection run for a specific integration.

Request Body

Field	Type	Required	Description
`integration_id`	string	Yes	Integration to collect evidence from

curl -X POST https://api.privabase.com/api/v1/evidence/collections/trigger \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "integration_id": "aws" }'

// JavaScript
await fetch('https://api.privabase.com/api/v1/evidence/collections/trigger', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ integration_id: 'aws' })
});

# Python
requests.post('https://api.privabase.com/api/v1/evidence/collections/trigger',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={'integration_id': 'aws'})

GET /api/v1/evidence/collections/:id 🔒

Get details of a specific collection run, including drift events detected and the evidence snapshot.

curl https://api.privabase.com/api/v1/evidence/collections/run-abc-123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": "run-abc-123",
    "integration_id": "aws",
    "status": "completed",
    "started_at": "2026-03-14T10:30:00Z",
    "completed_at": "2026-03-14T10:30:12Z",
    "evidence_count": 47,
    "drift_events": [
      {
        "id": "drift-001",
        "control_id": "soc2-cc6.1",
        "severity": "high",
        "description": "S3 bucket public access enabled",
        "previous_status": "passing",
        "current_status": "failing"
      }
    ],
    "snapshot": {
      "evidence_count": 47,
      "passing_count": 44,
      "failing_count": 2,
      "warning_count": 1
    }
  }
}

Evidence Timeline

GET /api/v1/evidence/timeline 🔒

Get a timeline of evidence status changes over time. Useful for compliance dashboards and audit trails.

Query Parameters

Param	Type	Description
`days`	integer	Number of days to look back (default 90)

curl "https://api.privabase.com/api/v1/evidence/timeline?days=30" \
  -H "Authorization: Bearer YOUR_TOKEN"

Drift Detection

GET /api/v1/evidence/drift 🔒

List detected compliance drift and regressions — controls that changed from passing to failing between collection runs.

Query Parameters

Param	Type	Description
`acknowledged`	boolean	Filter by acknowledgment status
`severity`	string	Filter: `critical`, `high`, `medium`, `low`
`limit`	integer	Max results (default 50)

curl "https://api.privabase.com/api/v1/evidence/drift?severity=critical&acknowledged=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

Evidence by Control

GET /api/v1/evidence/controls/:controlId 🔒

Get all evidence collected for a specific compliance control across all integrations.

curl https://api.privabase.com/api/v1/evidence/controls/soc2-cc6.1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Export Evidence Package

GET /api/v1/evidence/export 🔒

Export a complete evidence package for auditor review. Includes manifest, snapshots, timeline, and per-control evidence.

curl https://api.privabase.com/api/v1/evidence/export \
  -H "Authorization: Bearer YOUR_TOKEN"

// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/evidence/export', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});
const pkg = await res.json();

# Python
resp = requests.get('https://api.privabase.com/api/v1/evidence/export',
    headers={'Authorization': 'Bearer YOUR_TOKEN'})
package = resp.json()['data']

Response

{
  "success": true,
  "data": {
    "manifest": {
      "exported_at": "2026-03-14T10:30:00Z",
      "account_id": "acc-123",
      "total_evidence": 142
    },
    "snapshots": [...],
    "timeline": [...],
    "controls": {
      "soc2-cc6.1": { "status": "passing", "evidence_count": 12 },
      "soc2-cc7.2": { "status": "failing", "evidence_count": 3 }
    }
  }
}