# Manage file groups in a file connector workspace

{% hint style="info" %}
Included in the Basic API.

The file connector requires a Professional or Enterprise license.
{% endhint %}

In a [file connector](https://docs.tonic.ai/app/setting-up-your-database/file-connector) workspace (`dataType` is `Files`), you use [file groups](https://docs.tonic.ai/app/setting-up-your-database/file-connector/file-connector-file-groups) to identify the data and configure data generation. Each file group contains a set of files that are of the same type (.csv, .json, .xml) and that have an identical format.

For a file group that contains .csv files, you also provide information about the file structure and parsing. This includes the escape character, quote character, null character, and delimiter.

When you set the .csv parsing options, you must properly escape any escapable characters. For example, in the API request body, to use `\N` as the null character,  you must use an extra `\` to escape the value. So instead of `"nullChar": "\N"`, the request body would include `"nullChar": "\\N"`.

## Getting the list of file groups <a href="#tonic-api-file-group-list" id="tonic-api-file-group-list"></a>

To retrieve the list of file groups in a file connector workspace, use:

[<mark style="background-color:blue;">**GET**</mark>**&#x20;/api/FileGroup**](https://app.tonic.ai/apidocs/index.html#/FileGroup/GetAllFileGroups)

You provide the identifier of the workspace.

The results contain an array of [`FileGroupResponseModel`](https://app.tonic.ai/apidocs/index.html#/models/FileGroupResponseModel) objects. Each object represents a file group.

`fileType` identifies the type of file in the group.

For a file group that contains .csv files, the object includes the delimiter configuration (`escapeChar`, `quoteChar`, `hasHeader`, `delimiter`, `nullChar`). If the files have a header row, then the object includes the header list.

For a file group that contains files from cloud storage, the `files` object contains `bucketKeyPair` objects.

```
{
  "id": "string",
  "name": "string",
  "files": [
    {
      "bucketKeyPair": {
        "bucketName": "string",
        "key": "string"
      },
      "expectedFileType": "csv"
    }
  ],
  "createdDate": "2023-08-17T16:24:46.8443973Z",
  "workspaceId": "string",
  "escapeChar": "string",
  "quoteChar": "string",
  "hasHeader": true,
  "delimiter": "string",
  "nullChar": "string",
  "fileType": "string",
  "csvHeaderColumns": [
    "string"
  ]
}
```

For a file group that contains files from a local file system, the `files` object contains `localFile` objects, and also indicates whether there are available generated files to download:

```
{
  "id": "string",
  "name": "string",
  "files": [
    {
      "localFile": {
        "fileName": "string",
        "oid": 0
      },
      "expectedFileType": "string"
    }
  ],
  "createdDate": "2023-08-17T16:24:46.8443973Z",
  "workspaceId": "string",
  "escapeChar": "string",
  "quoteChar": "string",
  "hasHeader": true,
  "delimiter": "string",
  "nullChar": "string",
  "fileType": "string",
  "csvHeaderColumns": [
    "string"
  ],
  "hasGeneratedFilesAvailable": true
}
```

## Managing cloud storage file groups <a href="#tonic-file-group-cloud-storage" id="tonic-file-group-cloud-storage"></a>

### Creating a cloud storage file group <a href="#tonic-file-group-create-cloud-storage" id="tonic-file-group-create-cloud-storage"></a>

For a file connector workspace that uses files from cloud storage, to create a file group, use:

[<mark style="background-color:green;">**POST**</mark>**&#x20;/api/FileGroup**](https://app.tonic.ai/apidocs/index.html#/FileGroup/SaveNewFileGroup)

You identify the workspace and provide the file group name. You also provide the list of files and, for a file group that contains .csv files, the delimiter configuration.

```
{
  "name": "string",
  "workspaceId": "string",
  "escapeChar": "string",
  "quoteChar": "string",
  "hasHeader": true,
  "delimiter": "string",
  "nullChar": "string",
  "files": [
    {
      "bucketKeyPair": {
        "bucketName": "string",
        "key": "string"
      },
      "expectedFileType": "string"
    }
  ]
}
```

### Updating a cloud storage file group <a href="#tonic-file-group-update-cloud-storage" id="tonic-file-group-update-cloud-storage"></a>

To update a file group that contains files from Amazon S3 or Google Cloud Storage, to change the files, use:

[<mark style="background-color:orange;">**PUT**</mark>**&#x20;/api/FileGroup**](https://app.tonic.ai/apidocs/index.html#/FileGroup/UpdateFileGroup)

In the request, you provide a [`FileGroupDefinitionModel`](https://app.tonic.ai/apidocs/index.html#/models/FileGroupDefinitionModel) object that contains a revised list of files. You cannot change the file group name, file type, or the .csv delimiter configuration.

## Managing local file file groups <a href="#api-file-groups-local" id="api-file-groups-local"></a>

### Creating a local files file group <a href="#tonic-file-group-create-local" id="tonic-file-group-create-local"></a>

To create a file group that contains files from a local file system, use:

[**POST /api/FileGroup/create\_local\_filegroup**](https://app.tonic.ai/apidocs/index.html#/FileGroup/SaveNewLocalFileGroup)

In the request, you provide a [`FileGroupDefinitionModel`](https://app.tonic.ai/apidocs/index.html#/models/FileGroupDefinitionModel) object that identifies the workspace and provides the file group name. If the file group contains .csv files, you also provide the delimiter configuration.

```
{
  "name": "string",
  "workspaceId": "string",
  "escapeChar": "string",
  "quoteChar": "string",
  "hasHeader": true,
  "delimiter": "string",
  "nullChar": "string",
}
```

### Adding a file to a local files file group <a href="#tonic-file-group-add-file-local" id="tonic-file-group-add-file-local"></a>

To add a file to a file group from a local file system, use:

[<mark style="background-color:green;">**POST**</mark>**&#x20;/api/FileGroup/upload\_local\_file**](https://app.tonic.ai/apidocs/index.html#/FileGroup/UploadLargeFile)

You identify the file group to add the file to, and include the file.&#x20;

## Deleting a file group <a href="#tonic-api-file-group-delete" id="tonic-api-file-group-delete"></a>

To remove a file group from a file connector workspace, use:

[<mark style="background-color:red;">**DELETE**</mark>**&#x20;/api/FileGroup**](https://app.tonic.ai/apidocs/index.html#/FileGroup/DeleteFileGroup)

In the request, you identify the workspace and the file group.

## Downloading generated files for a local files file group <a href="#tonic-api-file-group-download-generated-files" id="tonic-api-file-group-download-generated-files"></a>

For a file group that contains files from a local file system, both the source files and the generated output files are stored in the Tonic Structural application database.

To identify file groups that available output files to download, use:

[<mark style="background-color:blue;">**GET**</mark>**&#x20;/api/FileGroup/generated\_file\_availability**](https://app.tonic.ai/apidocs/index.html#/FileGroup/GetAllFileGroupDownloadabilityStatus)

In the request, you provide the workspace identifier.

The response contains a list of identifiers for file groups that have generated files available to download.

To download the available files for a file group, use:

[<mark style="background-color:blue;">**GET**</mark>**&#x20;/api/FileGroup/download/{workspaceId}/{fileGroupId}**](https://app.tonic.ai/apidocs/index.html#/FileGroup/DownloadCsvWithSyntheticData)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tonic.ai/app/api/quick-start-guide/tonic-api-file-groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.