Getting started

The Files API allows you to upload, download, and manage files and searchable documents for your bots and integrations in Botpress Cloud.

Files can be in any text or binary format, and documents (such as PDF, Microsoft Office, HTML, CSV, etc.) can be indexed to be used for semantic search in RAG (Retrieval Augmented Generation) implementations. Files are private by default but can be made publicly accessible through a permanent URL that’s unique for each file.

When uploading a file and linking it to a knowledge base, you must index the file or else you will get an infinite loading loop when trying to open the file from the knowledge base.

To get started

1. Get familiarized with the different API endpoints available.

2. Review the instructions on how to authenticate with the API.

3. Check out the How-To guides (see left sidebar) for examples on how to use the Files API in different scenarios.

4. Try calling the list files API endpoint as shown below.

Using cURL

Calling the Files API can be done using any HTTP client, such as curl, axios, or fetch. Here’s an example using curl:

token="$YOUR_BOTPRESS_TOKEN"
bot_id="$YOUR_BOT_ID"
# List your bot's files
curl -H "Authorization: bearer $token" -H "x-bot-id: $bot_id" https://api.botpress.cloud/v1/files

Using the Official TypeScript Client

The official TypeScript client is available as an NPM package. You can install it using any of the following command:

npm

npm install @botpress/client

Once installed, you can import the client and use it in your TypeScript code:

import { files } from '@botpress/client'

const main = async () => {
    const token = process.env.TOKEN
    const botId = process.env.BOT_ID

    const client = new files.Client({
        token,
        botId,
    })

    const response = await files.listFiles({})
    console.log(response.files)
}

void main()

Security

Access Policies

A file can specify a list of special access policies:

• public_content: Unauthenticated users can read contents (but not metadata) of the file through a unique permanent URL provided by the API for each file. Without this policy the file URL returned by the API will be temporary and will expire after a short period of time.
• integrations: Grants read, search, list access to all integrations of the bot that owns the file.

Specifying the access policies for a file is completely optional and if not specified the file will be private by default and can only be accessed by the bot or integration that created it.

Important

If a file was created by a bot (not an integration) all workspace members (except those with Viewer and Billing roles) that have access to the bot will be able to read, update, or delete the file regardless of the access policies specified.

Permissions

Principal	Permissions
Public (unauthenticated/unauthorized users)	Can only download files that have the public_content access policy.
Bot	Owns and manages its files with full permissions to access and manage them, regardless of the user that created the file.
Integration	Has all permissions on the files that were created by that integration for the bot they’re installed on.
Viewer workspace member	Can read, search, and list all files for the bot, regardless of creator, but can’t create or delete files.
Developer, Manager or Administrator workspace member	Has all permissions on the bot’s files, regardless of creator.
Billing Manager workspace member	No permissions on files.

Note

The List Files API endpoint will filter out files that aren’t accessible to the user calling that API endpoint.

Pricing

There are two types of storage: File Storage and Vector DB Storage. All files count toward your workspace’s File Storage usage. Indexed files also count toward your workspace’s Vector DB Storage usage.

For full details on pricing please check our Pricing page.

Quotas/Limits

Category	Limit
Maximum uploaded file size	1 GB
Maximum payload size
Rate limits	Same as all other endpoints of our public API
Tags	As defined in the Limits and Quotas of Botpress Cloud
Search - Query	1 KB maximum
Search - Results	Maximum number of results: 50