# Query file list

Lists files accessible to a connector. First get the file `uri` from the response and then preview the file.

```text
GET https://moi.matrixorigin.cn/newmoi/connectors/files/list
```

## Preparation before calling

Prepare the personal access token, target workspace ID, and connector ID that have access to the target workspace. Only connectors that support file enumeration can call this interface.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: The workspace ID to be queried, passed through the `X-Workspace-ID` Header.
- `$CONNECTOR_ID`: The connector ID of the file to be enumerated, passed through the `connector_id` query parameter.

## Request example

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/files/list?connector_id=$CONNECTOR_ID&limit=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## Query parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `connector_id` | string | Yes | The connector ID. |
| `cursor` | string | No | The cursor returned from the previous page. |
| `limit` | integer | No | This page returns the quantity. The default value is `20`. |
| `dir` | string | no | Directory relative to the connector configuration root. |
| `file_types` | integer[] | No | Filter only the file type codes of ordinary files. Pass this parameter repeatedly, for example `file_types=7&file_types=25`. Directories are always returned and are not filtered by this parameter. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.


### File type codes

`file_types` and response `type` use these codes:

| Code | Type | Code | Type |
| --- | --- | --- | --- |
| `0` | Unrecognized | `1` | TXT |
| `2` | PDF | `3` | Generic image |
| `4` | PPT | `5` | Word |
| `6` | Markdown | `7` | CSV |
| `8` | Parquet | `9` | SQL |
| `10` | Table of contents | `11` | DOCX |
| `12` | PPTX | `13` | WAV |
| `14` | MP3 | `15` | AAC |
| `16` | FLAC | `17` | MP4 |
| `18` | MOV | `19` | MKV |
| `20` | PNG | `21` | JPG |
| `22` | JPEG | `23` | BMP |
| `24` | XLS | `25` | XLSX |
| `27` | HTM | `28` | HTML |
| `29` | EML | `30` | MSG |
| `31` | P7S | `32` | DWG |
| `33` | DXF | `34` | FAS |
| `35` | DOC | `101` | ZIP |
| `102` | RAR | `103` | 7Z |
| `104` | TAR | `105` | TAR.GZ |
| `106` | TAR.BZ2 | `107` | GZ |
| `108` | BZ2 |  |  |

`limit` is the amount used by the connector when reading a page. After applying `file_types` filter, the actual number of ordinary files returned by this page may be less than `limit`. Connectors that support cursor paging return the next page cursor when `has_more` is `true`; connectors that do not support paging return an empty cursor and `has_more=false`.

## Successful response

Returns `200` on success.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "files": [
      {
        "uri": "/orders.csv",
        "filename": "orders.csv",
        "size": 1024,
        "type": 1,
        "path": "/",
        "create_time": 0,
        "update_time": 0
      }
    ],
    "cursor": "next_cursor",
    "has_more": true
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.files` | object[] | Current page file; may be omitted or empty array when there is no file. |
| `data.files[].uri` | string | File URI, which can be used for subsequent previews. |
| `data.files[].filename` | string | File name. |
| `data.files[].size` | integer | File size in bytes. |
| `data.files[].type` | integer | File type code. |
| `data.files[].path` | string | File path within the connector. |
| `data.files[].create_time` | integer | The Unix timestamp of the file creation time. The current file list implementation returns `0`. |
| `data.files[].update_time` | integer | Unix timestamp of when the file was updated. The current file list implementation returns `0`. |
| `data.cursor` | string | Next page cursor. Only used for next request if `data.has_more` is `true`. |
| `data.has_more` | boolean | Whether there is still a next page. |

In field paths, `[]` means each item in an array. For example, `data.files[].uri` is the `uri` field of each item in `data.files`.

## Error response

```json
{
  "code": "ErrServer",
  "msg": "server error",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `—`
  - The query parameter format is invalid. The response uses the `error` field and does not use the standard `code` field.
  - Fix `connector_id`, cursor or `limit` and try again.
* - `500`
  - `ErrServer`
  - The connector does not exist, is not accessible, does not support enumerating files, or the service failed to read the file list.
  - Check the connector ID and access permissions; verify that the connector supports file enumeration and try again.
```

## Follow-up operations

Save the `uri` and connector ID of the target file. When you need to confirm the file content, use these two values ​​[preview file](preview-file.md).