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.
ImportantWhen 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 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.
ImportantIf 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

PrincipalPermissions
Public (unauthenticated/unauthorized users)Can only download files that have the public_content access policy.
BotOwns and manages its files with full permissions to access and manage them, regardless of the user that created the file.
IntegrationHas all permissions on the files that were created by that integration for the bot they are installed on.
Viewer workspace memberCan read, search, and list all files for the bot, regardless of creator, but cannot create or delete files.
Developer, Manager or Administrator workspace memberHas all permissions on the bot’s files, regardless of creator.
Billing Manager workspace memberNo permissions on files.
NoteThe List Files API endpoint will filter out files that are not 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

  • Maximum file size: 100 MB
  • 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
    • Maximum number of results: 50