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.

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

pnpm install @botpress/client

yarn add @botpress/client

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

import dotenv from 'dotenv'
import { Client } from '@botpress/client'

dotenv.config()

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

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

  const response = await client.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.

Permissions

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