> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-charmenta-pr-732.mintlify.site/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](/api-reference/files-api/how-tos/manage-files#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.

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  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={null}
  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
  ```
</CodeGroup>

## Listing existing files of a bot

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

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  const res = await client.listFiles({})
  const files = res.files
  ```

  ```ts Calling the API directly theme={null}
  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
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  const { files } = await client.listFiles({
    tags: {
      category: 'Sales',
    },
  })
  ```

  ```ts Calling the API directly theme={null}
  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
  ```
</CodeGroup>

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:

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  const { files } = await client.listFiles({
    tags: {
      category: ['Sales', 'Marketing'],
    },
  })
  ```

  ```ts Calling the API directly theme={null}
  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
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  const { files } = await client.listFiles({
    tags: {
      integrationName: {
        exists: false
      }
    }
  })
  ```

  ```ts Calling the API directly theme={null}
  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
  ```
</CodeGroup>

#### `not`

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

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  const { files } = await client.listFiles({
    tags: {
      integrationName: {
        not: 'webchat', // Could be a string or an array of strings
      },
    },
  })
  ```

  ```ts Calling the API directly theme={null}
  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
  ```
</CodeGroup>

#### `in`

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

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  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={null}
  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
  ```
</CodeGroup>

### Pagination

The [List Files](/api-reference/files-api/how-tos/manage-files#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={null}
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:

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  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={null}
  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.
      },
    },
  })
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```ts Using the Botpress Client theme={null}
  await client.deleteFile({ id: "YOUR_FILE_ID" })
  ```

  ```ts Calling the API directly theme={null}
  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}`,
    },
  })
  ```
</CodeGroup>