Start a chunked upload session

Start a chunked upload session for large files with no size limit.

When to use: Use this endpoint instead of POST /v1/documents/submit when your files exceed 50 MB or when you want resumable uploads that tolerate network interruptions.

Flow:

1. Call this endpoint to create an upload session — get sessionId and per-file fileId, chunkSizeBytes, totalChunks
2. Upload each file in order using PUT /v1/documents/upload/{sessionId}/files/{fileId}/chunks/{chunkIndex}
3. The last chunk automatically triggers compliance processing
4. Optionally poll GET /v1/documents/upload/{sessionId}/status to track upload progress

Submission Modes (Mutually Exclusive): Provide EITHER complianceReviewId (append to existing review) OR businessEntityId (creates a new compliance review). Cannot provide both or neither.

Framework and Control (Required for businessEntityId mode): When using businessEntityId, also provide complianceFrameworkId and controlId to specify which framework and control to use for the new review.

Session expiry: Sessions expire after 24 hours. Expired sessions return 410 Gone on chunk upload.

Request fields:

• files - Required. List of files to upload with fileName and fileSize (bytes)
• complianceReviewId - Required if no businessEntityId. Existing review to append to
• businessEntityId - Required if no complianceReviewId. Entity ID for new review
• complianceFrameworkId - Required with businessEntityId. Framework for the new review
• controlId - Required with businessEntityId. Control for the new review
• isConsolidated - Optional. Merge all files into a single analysis
• selectedControlItemIds - Optional JSON array of control item ULIDs to target specific items
• selectedControlClusterIds - Optional JSON array of cluster ULIDs. All non-obsolete items within those clusters are included. Unioned with selectedControlItemIds if both are provided.

Control Item Selection: Use selectedControlClusterIds, selectedControlItemIds, or both to narrow the analysis scope:

• Both provided → union of cluster items and individual items
• Clusters only → all non-obsolete items within those clusters
• Items only → only those specific items
• Neither → all non-obsolete items across the entire control (default)

Invalid cluster IDs (not belonging to the active control) return 422.