API Reference

Upload File

POST/api/v2/datasets/{datasetRid}/files/{filePath}/upload

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Uploads a File to an existing Dataset. The body of the request must contain the binary content of the file and the Content-Type header must be application/octet-stream. By default the file is uploaded to a new transaction on the default branch - master for most enrollments. If the file already exists only the most recent version will be visible in the updated view.

Advanced Usage

See Datasets Core Concepts for details on using branches and transactions. To upload a file to a specific Branch specify the Branch's name as branchName. A new transaction will be created and committed on this branch. By default the TransactionType will be UPDATE, to override this default specify transactionType in addition to branchName. See createBranch to create a custom branch. To upload a file on a manually opened transaction specify the Transaction's resource identifier as transactionRid. This is useful for uploading multiple files in a single transaction. See createTransaction to open a transaction.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:datasets-write.

Path parameters

datasetRid

string

The Resource Identifier (RID) of a Dataset.

filePath

string

The path to a File within Foundry. Examples: my-file.txt, path/to/my-file.jpg, dataframe.snappy.parquet.

Query parameters

branchName

string

optional

The name of the Branch on which to upload the File. Defaults to master for most enrollments.

transactionType

string (enum)

optional

The type of the Transaction to create when using branchName. Defaults to UPDATE.

Enum values: APPEND, UPDATE, SNAPSHOT, DELETE

transactionRid

string

optional

The Resource Identifier (RID) of the open Transaction on which to upload the File.

preview

boolean

optional

Enables the use of preview functionality.

Request body

body

string

Response body

File

object

Hide children

path

string

The path to a File within Foundry. Examples: my-file.txt, path/to/my-file.jpg, dataframe.snappy.parquet.

transactionRid

string

The Resource Identifier (RID) of a Transaction.

sizeBytes

string

optional

updatedTime

string

Examples

Request

Copied!

curl -X POST \
	-H "Content-type: application/octet-stream" \
	-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/datasets/ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da/files//upload?branchName=master&transactionType=APPEND&transactionRid=ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4&preview=true" \
	-d '@/path/to/file'

Response

Copied!

{
  "transactionRid": "ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4"
}