Create an upload session in a writable Storage workspace.
Create an upload session in a writable Storage workspace. The request enforces Storage access, workspace ownership, and entry lifecycle state.
curl --request POST \
--url https://api.revoengine.com/api/v1/storage/workspaces/{workspaceId}/uploads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "contracts.csv"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'contracts.csv'})
};
fetch('https://api.revoengine.com/api/v1/storage/workspaces/{workspaceId}/uploads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.revoengine.com/api/v1/storage/workspaces/{workspaceId}/uploads"
payload = { "name": "contracts.csv" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)Authorizations
Bearer JWT token or API Key (sk-*).
Path Parameters
Body
Retention for the finalized file. Duration starts at finalization; null means no expiration.
Show child attributes
Show child attributes
Parent folder id. Required for create mode when uploading into a folder.
"00000000-0000-4000-8000-000000000000"
Optional configured storage id for root-level uploads. Omit for managed default storage. Ignored when parentStorageEntryId is provided or when replacing an existing file.
"00000000-0000-4000-8000-000000000001"
Existing storage entry id to replace instead of creating a new file.
"00000000-0000-4000-8000-000000000002"
Expected current version of the file being replaced. The upload is rejected if the file changed after overwrite confirmation.
x >= 03
File name. Required for create mode.
"contracts.csv"
Expected content type.
"text/csv"
Expected size in bytes.
x >= 01048576
Logical storage lifecycle tier. Select only when creating a new file or upload session; existing files keep their tier. HOT: Active files used in live workflows, previews, and frequent downloads. WARM: Completed or less-active business files that are still occasionally accessed. COLD: Compliance snapshots, historic imports, and retained evidence that is rarely opened. FROZEN: Deep archive or legal-hold data kept mainly for audit or recovery obligations.
HOT, WARM, COLD, FROZEN "HOT"
Byte-transfer mode. Use "direct" when the client sends the complete file to the returned temporary upload target, "chunked" for explicit numbered parts, and "incremental" for server-assigned part numbering by default. Incremental sessions can still re-upload a specific part number when repairing an upload.
direct, chunked, incremental "incremental"
Post-finalize compute mode for this upload session. Defaults to sync for XLSX and text/* sessions and none for other binary sessions; an explicit value always overrides the default.
none, sync, async "sync"
Independent validation and undeclared-column policies for an uploaded XLSX, CSV, or TSV. Defaults to fallback validation with additional columns allowed; strict validation defaults to rejecting additional columns. The raw file is preserved.
Show child attributes
Show child attributes
Structured file write mode. Use "direct" for a predeclared CSV/XLSX layout with row-only XLSX parts. Use the default "staged" mode for independent requests that may be retried, replaced, reordered, or use inferred columns, sparse cells, formulas, or dynamic worksheets. For direct XLSX, declare every worksheet and its table.columns before the first append.
staged, direct "direct"
CSV/TSV dialect used when row payloads are appended or direct uploaded bytes are indexed.
Show child attributes
Show child attributes
Shared tabular layout. XLSX accepts multiple worksheets; CSV/TSV accepts one logical sheet used for column keys, types, and schema diagnostics. In writeMode "direct", configure table.columns for every declared sheet.
Show child attributes
Show child attributes
File metadata. Values may use any JSON type. Maximum 16 KiB and 64 top-level keys. Top-level keys starting with "__" are reserved for backend use.
{ "scope": "integration", "source": "sdk" }
Suppress Storage lifecycle events for the finalized file. Omit to preserve the existing setting on replacement; false explicitly enables events.
Optional external reference id.
Optional external reference type.
Optional external reference version.
Whether the finalized entry should be restricted.
Explicit allowed group ids for the finalized entry.
Explicit allowed user ids for the finalized entry.
Response
OK.
curl --request POST \
--url https://api.revoengine.com/api/v1/storage/workspaces/{workspaceId}/uploads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "contracts.csv"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'contracts.csv'})
};
fetch('https://api.revoengine.com/api/v1/storage/workspaces/{workspaceId}/uploads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.revoengine.com/api/v1/storage/workspaces/{workspaceId}/uploads"
payload = { "name": "contracts.csv" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)