Event Types

Reference for chain-of-custody event types returned by GET /api/collections/{id}/events.

note

These are persisted chain-of-custody events, not Server-Sent Events. Each event records who did what, when, and the resulting collection state. They are returned newest-first as a JSON array.

Event Type Reference

The event_type field is one of the following (the ChainOfCustodyEventType enum):

Event Type	When
collection_created	A collection is created
credentials_validated	Credential validation completed
collection_started	Worker begins execution
collection_paused	Collection paused
collection_resumed	Collection resumed / re-queued
collection_completed	All endpoints finished
data_collected	Data/files collected from an endpoint
endpoint_skipped	An endpoint was skipped
analyst_assigned	An analyst was assigned
analyst_reviewed	An analyst reviewed the collection
analyst_signed_off	An analyst signed off
zip_created	Delivery ZIP created
sas_url_generated	Download SAS URL generated
customer_notified	Customer notified (also used for download-info access)
collection_delivered	Collection delivered
collection_archived	Collection soft-deleted/archived
error_occurred	An error was recorded
credentials_revoked	Credentials revoked
collection_cancelled	Collection cancelled

Common Shape

Every event in the events array has the same envelope (see Timeline Events):

{
  "id": "evt_001",
  "event_type": "collection_created",
  "actor_name": "Jane Smith",
  "actor_type": "customer",
  "timestamp": "2024-01-15T10:30:00Z",
  "new_state": "pending",
  "event_data": { "...": "event-specific payload" }
}

Representative event_data Payloads

The event_data object varies by event_type. Examples below are illustrative — exact keys depend on what the producing route recorded.

collection_created

{
  "connector_id": "conn_slack001",
  "credential_id": "cred_abc123",
  "priority": "high",
  "scope_config": { "...": "..." }
}

analyst_signed_off

{
  "analyst_name": "John Doe",
  "notes": "Verified all files.",
  "checklist": {
    "filesCollected": true,
    "hashesVerified": true,
    "apiLogsReviewed": true,
    "chainComplete": true
  },
  "files_collected": 234
}

collection_archived

{
  "action": "soft_delete",
  "deleted_by_analyst_name": "John Doe",
  "collection_snapshot": {
    "status_at_deletion": "completed",
    "case_reference": "CASE-2024-001"
  }
}

Tracking Live Progress

There is no push channel for collection progress. To follow a running collection, poll GET /api/collections/{id} for the status and progress block, and read this timeline for the audit trail.