Download Collection

Get a secure download link for a delivered collection.

GET /api/collections/{id}/download

Authorization

• Customer: Can download their own delivered collections
• Analyst / Admin: Can download any delivered collection

note

Collections must have status delivered to be downloadable. Accessing the download info logs a chain-of-custody event.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Collection ID

Response

{
  "collection_id": "col_abc123",
  "company_name": "Acme Corporation",
  "platform_name": "Slack",
  "download_url": "https://tracestorage.blob.core.windows.net/collections/col_abc123/delivery.zip?sv=2021-06-08&...&sig=...",
  "zip_password": "Tr4c3s-2024-ABC123",
  "file_size": 52428800,
  "files_included": 234,
  "expires_at": "2024-01-17T22:00:00Z",
  "delivered_at": "2024-01-17T09:30:00Z"
}

Response Fields

Field	Description
collection_id	Collection identifier
company_name	Owning customer's company name
platform_name	Connector platform
download_url	Time-limited Azure Blob SAS URL for download
zip_password	Decrypted password to extract the ZIP archive
file_size	Total size of the download in bytes
files_included	Number of files in the archive
expires_at	When the download link expires
delivered_at	When the collection was delivered

Security

• SAS URLs are time-limited (12 hours by default)
• ZIP password is unique per collection
• Download logged in chain of custody
• HTTPS only - all downloads are encrypted in transit

Chain of Custody Event

Each download request is logged:

{
  "event_type": "download_requested",
  "actor_id": "cus_xyz789",
  "actor_type": "customer",
  "timestamp": "2024-01-17T10:00:00Z",
  "event_data": {
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0...",
    "sas_expires_at": "2024-01-17T22:00:00Z"
  }
}

Example Request

curl -X GET "https://api.traces.io/api/collections/col_abc123/download" \
  -H "Authorization: Bearer <token>"

Download the File

Using the returned SAS URL:

# Using curl
curl -o collection.zip "https://tracestorage.blob.core.windows.net/..."

# Using wget
wget -O collection.zip "https://tracestorage.blob.core.windows.net/..."

Extract the Archive

# Using the provided password
unzip -P "Tr4c3s-2024-ABC123" collection.zip

Error Responses

400 Bad Request

Collection not yet delivered:

{
  "error": {
    "code": "NOT_READY",
    "message": "Collection is not yet available for download"
  }
}

403 Forbidden

Customer accessing another's collection:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied"
  }
}

404 Not Found

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

410 Gone

The download link has expired:

{
  "error": {
    "code": "EXPIRED",
    "message": "Download link has expired. Please contact support."
  }
}