> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage files

## Getting the file's metadata

To get the details of a file you can use the [Get File](https://botpress.com/docs/api-reference/files-api/how-tos/manage-files.md#getting-the-file’s-metadata) API endpoint.

You can also use this endpoint to retrieve a new temporary pre-signed URL to download a file if the previous pre-signed URL has already expired.

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import { Client } from '@botpress/client'

const client = new Client({
  token: process.env.BOTPRESS_PAT,
  botId: process.env.BOTPRESS_BOT_ID,
})

const file = await client.getFile({ id: "YOUR_FILE_ID" });
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const result = await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const file = response.file
```

## Listing existing files of a bot

To list all the files of a bot you can use the [List Files](https://botpress.com/docs/api-reference/files-api/how-tos/manage-files.md#listing-existing-files-of-a-bot) API endpoint.

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const res = await client.listFiles({})
const files = res.files
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const result = await fetch('https://api.botpress.cloud/v1/files', {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files
```

### Filtering by tag values

If you need to filter files by tags, pass in the `tags` parameter, which is an object containing tags as key-value pairs. This will only return files that include all the tags (and corresponding values) that you specify.

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { files } = await client.listFiles({
  tags: {
    category: 'Sales',
  },
})
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  category: 'Sales',
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files
```

You can also pass in an array of strings as the tag's value. This returns files that have that tag with any of the specified values:

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { files } = await client.listFiles({
  tags: {
    category: ['Sales', 'Marketing'],
  },
})
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  category: ['Sales', 'Marketing'],
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files
```

### Advanced tag filtering

Instead of passing in the value of a tag, you can pass in an object with the `exists`, `not` or `in` properties to allow for more advanced filtering.

#### `exists`

Use the `exists` property to specify whether a tag should be present or absent on the returned files:

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { files } = await client.listFiles({
  tags: {
    integrationName: {
      exists: false
    }
  }
})
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  integrationName: {
    exists: false
  }
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files
```

#### `not`

Use the `not` property to specify a value (or an array of values) to exclude for a given tag:

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { files } = await client.listFiles({
  tags: {
    integrationName: {
      not: 'webchat', // Could be a string or an array of strings
    },
  },
})
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  integrationName: {
    not: 'webchat' // Could be a string or an array of strings
  }
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files
```

#### `in`

Use the `in` property to specify a value (or an array of values) to include for a given tag:

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const { files } = await client.listFiles({
  tags: {
    integrationName: {
      in: ['webchat', 'whatsapp'], // Could be a string or an array of strings
    },
  },
})
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import qs from 'qs' // You'll need to install this package first using your favorite package manager

const tags = {
  integrationName: {
    in: ['webchat', 'whatsapp'] // Could be a string or an array of strings
  }
}

const params = qs.stringify({ tags })

const result = await fetch('https://api.botpress.cloud/v1/files?' + params, {
  method: 'GET',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})

const response = await result.json()
const files = response.files
```

### Pagination

The [List Files](https://botpress.com/docs/api-reference/files-api/how-tos/manage-files.md#listing-existing-files-of-a-bot) API endpoint will return by default the 20 most recent files your bot has. If you need to list older files you can use the `nextToken` property returned in the API response to retrieve the next page (if any) of files. The `nextToken` will be included for each page if there are files remaining to be listed.

For example:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
let res = await client.listFiles({})
const files = res.files

// You can put this in a loop to retrieve all the files if needed
if (res.meta.nextToken) {
  res = await client.listFiles({ nextToken: res.meta.nextToken })
  files.push(...res.files)
}
```

## Updating the file metadata

Only the tags and access policies of a file can be updated.

Here's an example of how to update the access policies and tags of a file using the Botpress Client:

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
const response = await client.updateFileMetadata({
  id: 'file_01K86HD0D5T3HFCGBEKQJFNKAD',
  accessPolicies: ['integrations'], // This value will replace the existing access policies of the file.
  tags: {
    // This acts as a "patch" or partial update, so only the tags specified here will be updated, the rest will remain unchanged. If you need to delete an existing tag, you can set it to a `null` value.
    category: 'Support', // This tag will be updated.
    knowledgeBaseName: null, // This tag will be deleted.
    subcategory: 'Technical', // This tag will be added.
    // Any other tags not specified here will remain unchanged.
  },
})

const updatedFile = response.file
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
  method: 'PUT',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
  body: {
    accessPolicies: ['integrations'], // This value will replace the existing access policies of the file.
    tags: {
      // This acts as a "patch" or partial update, so only the tags specified here will be updated, the rest will remain unchanged. If you need to delete an existing tag, you can set it to a `null` value.
      category: 'Support', // This tag will be updated.
      knowledgeBaseName: null, // This tag will be deleted.
      subcategory: 'Technical', // This tag will be added.
      // Any other tags not specified here will remain unchanged.
    },
  },
})
```

## Updating file content

If you need to update the content of a file, you can create a new file with the updated content and then delete the old file. The file ID will change in this case.

## Deleting a file

To delete a file you can use the "Delete File" API endpoint.

```ts Using the Botpress Client theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await client.deleteFile({ id: "YOUR_FILE_ID" })
```

```ts Calling the API directly theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await fetch('https://api.botpress.cloud/v1/files/YOUR_FILE_ID', {
  method: 'DELETE',
  headers: {
    'x-bot-id': 'YOUR_BOT_ID_GOES_HERE',
    Authorization: `Bearer ${process.env.BOTPRESS_PAT}`,
  },
})
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.