--- title: "Create File Resource" method: POST path: "/v2/storage/files/prepare" tags: ["Files"] --- # Create File Resource `POST /v2/storage/files/prepare` ## Request - Base URL: `https://connection.keboola.com` - URL: `https://connection.keboola.com/v2/storage/files/prepare` - Auth: one of: - API key in header `X-StorageApi-Token` - API key in header `X-KBC-ManageApiToken` - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) This method allows you to upload a file to KBC File Storage. The upload should be done in two steps: 1. Create a new file resource (use this API call). 2. Use the provided credentials to actually upload the file data to the storage provider. For a more detailed guide on the file upload, see the corresponding part of the [Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#manually-uploading-a-file). File Storage is used for storing arbitrary files. This is used for data imported into tables and data exported from tables. Additionally, the File storage can be used for data backup and exchange between project participants. By default, all files are stored for **15 days**. They can be stored permanently by using the `isPermanent` parameter. Files can also be tagged to categorize file uploads. When the `X-KBC-RunId` header is provided, it is stored as the file `runId`. Internally, all files are stored encrypted and are private. When you access the file through the API, a URL with one hour expiration is generated. Large files may be split into slices (chunks). A sliced file must have the `isSliced` parameter set to `true`. In that case the provided key (blob) points to a **manifest file**. The manifest file contains the actual list of uploaded chunks. When uploading a sliced file, you have to use the provided key as a prefix for chunks and generate the manifest file with the list of uploaded chunks. See the [Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#working-with-sliced-files) for a detailed guide on sliced files. The accepted request attributes depend on the file storage provider of the project (`S3FilePrepareRequest` for AWS, `AbsFilePrepareRequest` for Azure, `GcsFilePrepareRequest` for GCP). The response contains provider-specific upload parameters: `uploadParams` (AWS), `absUploadParams` (Azure) or `gcsUploadParams` (GCP). ## Request body - union - AbsFilePrepareRequest - `name` string, required: File name. Sanitized to a valid filename. - `isPermanent` boolean: Keeps a file forever. If false, the file will be deleted after 15 days. - `isSliced` boolean: If true, multiple chunks of a file are allowed to be uploaded and the provided key points to a manifest file. - `contentType` string: File MIME type. - `tags` string[]: Assigns one or more tags to the file. - `sizeBytes` integer, nullable: File size in bytes. - `federationTokenRequired` boolean - GcsFilePrepareRequest - `name` string, required: File name. Sanitized to a valid filename. - `isPermanent` boolean: Keeps a file forever. If false, the file will be deleted after 15 days. - `isSliced` boolean: If true, multiple chunks of a file are allowed to be uploaded and the provided key points to a manifest file. - `contentType` string: File MIME type. - `tags` string[]: Assigns one or more tags to the file. - `sizeBytes` integer, nullable: File size in bytes. - `federationTokenRequired` boolean - S3FilePrepareRequest - `name` string, required: File name. Sanitized to a valid filename. - `isPublic` boolean: Whether the file should be publicly accessible via a direct URL. - `notify` boolean: Notifies project administrators that a file was uploaded. - `isPermanent` boolean: Keeps a file forever. If false, the file will be deleted after 15 days. - `isSliced` boolean: If true, multiple chunks of a file are allowed to be uploaded and the provided key points to a manifest file. - `isEncrypted` boolean: If true, the file content will be encrypted in the provided storage. Azure and Google Cloud always create encrypted files regardless of this setting. - `federationToken` boolean: Must be set to `true`; requests temporary federation token credentials for the upload. Form uploads without it are deprecated and rejected. - `contentType` string: File MIME type. - `tags` string[]: Assigns one or more tags to the file. - `sizeBytes` integer, nullable: File size in bytes. - `federationTokenRequired` boolean ## Response `200` Created file resource including provider-specific upload parameters. - FilePrepareResponse - `id` integer, required: Identifier of the file. - `created` string, required: Creation time of the file, ISO 8601 with a `+hhmm` offset. - `isPublic` boolean, required: Whether the file is publicly accessible via a direct URL. - `isSliced` boolean, required: Whether the file consists of multiple slices (chunks) described by a manifest file. - `isEncrypted` boolean, required: Whether the file content is encrypted in the storage. - `name` string, required: Sanitized file name. - `fileType` string, required: Human readable file type derived from the file name. - `url` string, required: Pre-signed download URL of the file. The URL expires after one hour. - `provider` 'aws' | 'azure' | 'gcp', required: File storage provider. - `region` string, required: Region of the file storage. - `sizeBytes` integer, nullable, required: File size in bytes, null when not known. - `tags` string[], required: Tags assigned to the file. - `maxAgeDays` integer, nullable, required: Number of days the file is kept before it expires. Null for permanent files. - `runId` string, nullable, required: Run ID taken from the X-KBC-RunId header when the file was created. - `runIds` string[], required: All run IDs derived from the hierarchical run ID. - `creatorToken` object, required: Token that created the file. - `id` integer, required - `description` string, required - `uploadParams` object: Upload parameters. Present only for the `aws` provider. - `key` string, required: S3 object key. For sliced files it is the prefix of the slices and of the manifest file. - `bucket` string, required: S3 bucket. - `acl` 'private' | 'public-read', required: ACL to use for the uploaded object. - `credentials` object, required: Temporary AWS credentials with write access to the key. - `AccessKeyId` string, required - `SecretAccessKey` string, required - `SessionToken` string, required - `Expiration` string, date-time, required - `x-amz-server-side-encryption` string: Present only when `isEncrypted` is true; the encryption header to send with the upload. - `absUploadParams` object: Upload parameters. Present only for the `azure` provider. - `blobName` string, required - `accountName` string, required - `container` string, required - `absCredentials` object, required: SAS credentials with write access to the container. - `SASConnectionString` string, required - `expiration` string, required: ISO 8601 with a `+hhmm` offset. - `gcsUploadParams` object: Upload parameters. Present only for the `gcp` provider. - `projectId` string, required - `bucket` string, required - `key` string, required - `access_token` string, required - `expires_in` integer, required: Token lifetime in seconds. - `token_type` string, required ## Other responses - `400`: Returned when the request is invalid (`filePrepare.validationError`) or when a form upload without `federationToken` is requested on AWS (`storage.files.formUploadIsDeprecated`). --- [API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)