Create Collection

Create a new data collection request.

POST /api/collections

Authorization

• Customer: Can create collections for themselves
• Analyst: Can create collections for any customer

Request Body

Field	Type	Required	Description
connector_id	string (uuid)	Yes	ID of the connector to use (must be in production status)
credential_id	string (uuid)	Yes	ID of the stored credentials (must match the connector)
case_reference	string	No	External case reference number
business_context	string	Yes	Reason for the collection
priority	string	No	Priority level: low, normal, high, urgent (default: normal)
scope_config	object	Yes	Collection scope configuration
runtime_parameter_values	object (string→string)	No	Values for the connector's runtime parameters (required ones must be supplied)
on_behalf_of_customer_id	string (uuid)	No	Analyst-only: create for a verified customer
on_behalf_of_reason	string	No	Analyst-only: reason (required with on_behalf_of_customer_id)

Scope Configuration

{
  scope_config: {
    date_range?: {
      from: string,  // ISO 8601 date
      to: string     // ISO 8601 date
    },
    filters?: {
      users?: string[],
      channels?: string[],
      workspaces?: string[],
      file_types?: string[]
    },
    estimated_volume_gb?: number
  }
}

Request Example

{
  "connector_id": "conn_slack001",
  "credential_id": "cred_abc123",
  "case_reference": "CASE-2024-001",
  "business_context": "Internal investigation - HR matter",
  "priority": "high",
  "scope_config": {
    "date_range": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T23:59:59Z"
    },
    "filters": {
      "channels": ["#general", "#engineering"],
      "file_types": ["pdf", "docx", "xlsx"]
    },
    "estimated_volume_gb": 5
  }
}

Response

Returns 201 Created:

{
  "id": "col_abc123",
  "status": "pending",
  "message": "Collection created and queued for processing"
}

Side Effects

Creating a collection triggers the following:

1. Collection record created in database (status pending)
2. Chain of custody event logged (collection_created)
3. validate-credentials job queued for async processing
4. For analyst on-behalf-of creations, the target customer is emailed

Example Request

curl -X POST "https://api.traces.io/api/collections" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_id": "conn_slack001",
    "credential_id": "cred_abc123",
    "business_context": "Legal hold - Project Alpha",
    "priority": "high",
    "scope_config": {
      "date_range": {
        "from": "2024-01-01T00:00:00Z",
        "to": "2024-01-31T23:59:59Z"
      }
    }
  }'

Error Responses

400 Bad Request

Missing or invalid fields:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "connector_id is required"
  }
}

404 Not Found

Connector or credential not found:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Connector not found"
  }
}