Upsert File

put https://api.botpress.cloud/v1/files

Creates or updates a file using the key parameter as unique identifier. Updating a file will erase the existing content of the file. Upload the file content by sending it in a PUT request to the uploadUrl returned in the response.

Log in to see full request history

To associate a file with a knowledge base, you must use these tags:

{
  ...yourTags,
  source: 'knowledge-base',
  kbId: 'kb-2f0a7ea639',
}

You can get the kbId from the URL on the Knowledge Base you want to upsert the file to. For example:

in the above image, the kbId would be kb-2f0a7ba679.

Body Params

Properties of the file to create or update.

key

string

required

Unique key for the file. Must be unique across the bot (and the integration, when applicable).

tags

object

File tags as an object of key-value pairs. Tag values should be of string (text) type.

size

number

required

File size in bytes. This will count against your File Storage quota. If the index parameter is set to true, this will also count against your Vector DB Storage quota.

index

boolean

Defaults to false

Set to a value of 'true' to index the file in vector storage. Only certain file formats are currently supported for indexing. Note that if a file is indexed, it will count towards both the Vector DB Storage quota and the File Storage quota of the workspace.

indexing

object

accessPolicies

array of strings

File access policies. Add "public_content" to allow public access to the file content. Add "integrations" to allow read, search and list operations for any integration installed in the bot.

accessPolicies

contentType

string

File content type. If omitted, the content type will be inferred from the file extension (if any) specified in key. If a content type cannot be inferred, the default is "application/octet-stream".

expiresAt

date-time

Expiry timestamp in ISO 8601 format with UTC timezone. After expiry, the File will be deleted. Must be in the future. Cannot be more than 90 days from now. The value up to minutes is considered. Seconds and milliseconds are ignored.

publicContentImmediatelyAccessible

boolean

Use when your file has "public_content" in its access policy and you need the file's content to be immediately accessible through its URL after the file has been uploaded without having to wait for the upload to be processed by our system.

If set to true, the x-amz-tagging HTTP header with a value of public=true will need to be sent in the HTTP PUT request to the uploadUrl in order for the upload request to work.

metadata

string

Custom metadata for the file expressed as an object of key-value pairs. The values can be of any type.

Headers

x-bot-id

string

required

Bot ID

x-workspace-id

string

required

Workspace ID

Responses

Response body

object

file

object

required

id

string

required

File ID

botId

string

required

The ID of the bot the file belongs to

key

string

required

Unique key for the file. Must be unique across the bot (and the integration, when applicable).

url

string

required

URL to retrieve the file content. This URL will be ready to use once the file is uploaded.

If the file has a public_content policy, this will contain the permanent public URL to retrieve the file, otherwise this will contain a temporary pre-signed URL to download the file which should be used shortly after retrieving and should not be stored long-term as the URL will expire after a short timeframe.

size

number | null

required

File size in bytes. Non-null if file upload status is "COMPLETE".

contentType

string

required

MIME type of the file's content

tags

object

required

The tags of the file as an object of key/value pairs

Has additional fields

metadata

object

required

Metadata of the file as an object of key/value pairs. The values can be of any type.

Has additional fields

createdAt

string

required

File creation timestamp in ISO 8601 format

updatedAt

string

required

File last update timestamp in ISO 8601 format

accessPolicies

array of strings

required

Access policies configured for the file.

accessPolicies*

index

boolean

required

Whether the file was requested to be indexed for search or not.

status

string

required

Status of the file. If the status is upload_pending, the file content has not been uploaded yet. The status will be set to upload_completed once the file content has been uploaded successfully.

If the upload failed for any reason (e.g. exceeding the storage quota or the maximum file size limit) the status will be set to upload_failed and the reason for the failure will be available in the failedStatusReason field of the file.

However, if the file has been uploaded and the index attribute was set to true on the file, the status will immediately transition to the indexing_pending status (the upload_completed status step will be skipped).

Once the indexing is completed and the file is ready to be used for searching its status will be set to indexing_completed. If the indexing failed the status will be set to indexing_failed and the reason for the failure will be available in the failedStatusReason field.

upload_pending upload_failed upload_completed indexing_pending indexing_failed indexing_completed

failedStatusReason

string

If the file status is upload_failed or indexing_failed this will contain the reason of the failure.

expiresAt

string

File expiry timestamp in ISO 8601 format

uploadUrl

string

required

URL to upload the file content. File content needs to be sent to this URL via a PUT request.

Response body

object

file

object

required

id

string

required

File ID

botId

string

required

The ID of the bot the file belongs to

key

string

required

Unique key for the file. Must be unique across the bot (and the integration, when applicable).

url

string

required

URL to retrieve the file content. This URL will be ready to use once the file is uploaded.

If the file has a public_content policy, this will contain the permanent public URL to retrieve the file, otherwise this will contain a temporary pre-signed URL to download the file which should be used shortly after retrieving and should not be stored long-term as the URL will expire after a short timeframe.

size

number | null

required

File size in bytes. Non-null if file upload status is "COMPLETE".

contentType

string

required

MIME type of the file's content

tags

object

required

The tags of the file as an object of key/value pairs

Has additional fields

metadata

object

required

Metadata of the file as an object of key/value pairs. The values can be of any type.

Has additional fields

createdAt

string

required

File creation timestamp in ISO 8601 format

updatedAt

string

required

File last update timestamp in ISO 8601 format

accessPolicies

array of strings

required

Access policies configured for the file.

accessPolicies*

index

boolean

required

Whether the file was requested to be indexed for search or not.

status

string

required

Status of the file. If the status is upload_pending, the file content has not been uploaded yet. The status will be set to upload_completed once the file content has been uploaded successfully.

If the upload failed for any reason (e.g. exceeding the storage quota or the maximum file size limit) the status will be set to upload_failed and the reason for the failure will be available in the failedStatusReason field of the file.

However, if the file has been uploaded and the index attribute was set to true on the file, the status will immediately transition to the indexing_pending status (the upload_completed status step will be skipped).

Once the indexing is completed and the file is ready to be used for searching its status will be set to indexing_completed. If the indexing failed the status will be set to indexing_failed and the reason for the failure will be available in the failedStatusReason field.

upload_pending upload_failed upload_completed indexing_pending indexing_failed indexing_completed

failedStatusReason

string

If the file status is upload_failed or indexing_failed this will contain the reason of the failure.

expiresAt

string

File expiry timestamp in ISO 8601 format

uploadUrl

string

required

URL to upload the file content. File content needs to be sent to this URL via a PUT request.

Language

Credentials

Bearer

PAT


xxxxxxxxxx
1
curl --request PUT \
2
     --url https://api.botpress.cloud/v1/files \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json