Initiate a single-PUT upload for files up to 5 GB. The response includes a pre-signed upload_url that the client should PUT the full file body to. After the PUT succeeds, call Complete upload at POST /v2/files/{file_id}/upload/complete.

The pre-signed upload_url is signed for server-side encryption with AWS KMS, so the PUT request must include the header x-amz-server-side-encryption: aws:kms. Omitting it (or sending a different value) fails the request with a signature mismatch (HTTP 403).

curl -X PUT "<upload_url>" \
-H "x-amz-server-side-encryption: aws:kms" \
-H "Content-Type: <type>" \
--data-binary @/path/to/file

Files larger than 5 GB must use the large-upload endpoint (POST /v2/files/large-upload) instead.

Once finalized, inspect the file with GET /v1/files/{file_id} and download it with GET /v1/files/{file_id}/download — no v2 read surface exists yet.

Returns 201 with the upload session details. Orphaned uploads that are not completed are eventually cleaned up.

Required scope: data:file_import or doc:file_import