Search documentation
karat

+

K

User Documentation ↗
Version 1.0

Upload File

POST/api/v1/datasets/{datasetRid}/files:upload

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 identifier as branchId. 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 branchId. 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 the Dataset on which to upload the File.

Query parameters

filePath
string

The File's path within the Dataset.

branchId
string
optional

The identifier (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 branchId. 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.

Request body

body
string

Response body

File
object
Hide child attributes

Hide child attributes

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!
1curl -X POST \ 2 -H "Content-type: application/octet-stream" \ 3 -H "Authorization: Bearer $TOKEN" \ 4 "https://$HOSTNAME/api/v1/datasets/ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da/files:upload?filePath=q3-data%252fmy-file.csv&branchId=master&transactionType=APPEND&transactionRid=ri.foundry.main.transaction.0a0207cb-26b7-415b-bc80-66a3aa3933f4" \ 5 --data-binary '@/path/to/file'

Response

Copied!
1{ 2 "path": "q3-data/my-file.csv", 3 "transactionRid": "ri.foundry.main.transaction.bf9515c2-02d4-4703-8f84-c3b3c190254d", 4 "sizeBytes": "74930", 5 "updatedTime": "2022-10-10T16:44:55.192Z" 6}

Error responses

Error Name
InvalidParameterCombinationError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe given parameters are individually valid but cannot be used in the given combination.
ParametersvalidCombinations, providedParameters
UploadFilePermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionThe provided token does not have permission to upload the given file to the given dataset and transaction.
ParametersdatasetRid, transactionRid, path
OpenTransactionAlreadyExistsError CodeCONFLICT
Status Code409
DescriptionA transaction is already open on this dataset and branch. A branch of a dataset can only have one open transaction at a time.
ParametersdatasetRid, branchId
CreateTransactionPermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionThe provided token does not have permission to create a transaction on this dataset.
ParametersdatasetRid, branchId
FileAlreadyExistsError CodeNOT_FOUND
Status Code404
DescriptionThe given file path already exists in the dataset and transaction.
ParametersdatasetRid, transactionRid, path
InvalidBranchIdError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe requested branch name cannot be used. Branch names cannot be empty and must not look like RIDs or UUIDs.
ParametersbranchId
BranchNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe requested branch could not be found, or the client token does not have access to it.
ParametersdatasetRid, branchId
AbortTransactionPermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionThe provided token does not have permission to abort the given transaction on the given dataset.
ParametersdatasetRid, transactionRid
DatasetNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe requested dataset could not be found, or the client token does not have access to it.
ParametersdatasetRid
TransactionNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe requested transaction could not be found on the dataset, or the client token does not have access to it.
ParametersdatasetRid, transactionRid
CommitTransactionPermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionThe provided token does not have permission to commit the given transaction on the given dataset.
ParametersdatasetRid, transactionRid
TransactionNotOpenError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe given transaction is not open.
ParametersdatasetRid, transactionRid, transactionStatus