> This page is for version 0.5.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.8.0: https://docs.nvidia.com/nemo-helix/v0.8.0/llms.txt
> - 0.7.1: https://docs.nvidia.com/nemo-helix/v0.7.1/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo-helix/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo-helix/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo-helix/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo-helix/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo-helix/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo-helix/v0.3.0/llms.txt
> - 0.2.0: https://docs.nvidia.com/nemo-helix/v0.2.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-helix/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server.

# List Filesets

GET /apis/files/v2/workspaces/{workspace}/filesets

List Filesets endpoint with filtering and pagination.

Supports filtering by name, description, purpose, storage_type, created_at, and updated_at via query parameters.
Returns paginated results with sorting options.

Reference: https://docs.nvidia.com/nemo-helix/documentation/reference/api-reference/files/list-filesets-apis-files-v-2-workspaces-workspace-filesets-get

## Request

### Path parameters

- `workspace` (string, required)

### Query parameters

- `page` (integer, optional, default: 1) — Page number.
- `page_size` (integer, optional, default: 10) — Page size.
- `sort` (enum, optional, default: -created_at) — The field to sort by. To sort in decreasing order, use `-` in front of the field name.
  - Allowed values: `created_at`, `-created_at`, `updated_at`, `-updated_at`, `name`, `-name`
- `filter` (FilesetFilter, optional) — Filter filesets by name, description, purpose, storage_type, created_at, and updated_at.

## Response

### 200

Successful Response

- `data` (list of FilesetOutput, required)
- `pagination` (PaginationData, optional) — Pagination information.
- `sort` (string, optional) — The field on which the results are sorted.
- `filter` (map from string to any, optional) — Filtering information.

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### FilesetFilter

Filter schema for listing filesets.

- `name` (FilesetFilterName, optional) — Filter by fileset name.
- `description` (FilesetFilterDescription, optional) — Filter by fileset description.
- `purpose` (enum, optional) — Filter by the purpose of the fileset (e.g., 'dataset', 'generic').
  - Allowed values: `dataset`, `environment`, `generic`, `model`
- `storage_type` (enum, optional) — Filter by the storage backend type (e.g., 'local', 'ngc').
  - Allowed values: `local`, `ngc`, `huggingface`, `s3`, `github`
- `created_at` (DatetimeFilter, optional) — Filter by creation date. Supports '$gte' (on or after) and '$lte' (on or before) datetime filters.
- `updated_at` (DatetimeFilter, optional) — Filter by update date. Supports '$gte' (on or after) and '$lte' (on or before) datetime filters.

### FilesetOutput

Response DTO for fileset operations.

- `id` (string, required)
- `name` (string, required)
- `workspace` (string, required)
- `description` (string, required)
- `purpose` (enum, required)
  - Allowed values: `dataset`, `environment`, `generic`, `model`
- `storage` (FilesetOutputStorage, required)
- `metadata` (FilesetMetadata, required) — Tagged metadata container - the key indicates the type. Example: metadata = FilesetMetadata( dataset=DatasetMetadataContent( schema=\{"columns": \["id", "name"]}, ) )
- `custom_fields` (map from string to any, required)
- `project` (string, required)
- `created_at` (string, required)
- `updated_at` (string, required)

### PaginationData

- `page` (integer, required) — The current page number.
- `page_size` (integer, required) — The page size used for the query.
- `current_page_size` (integer, required) — The size for the current page.
- `total_pages` (integer, required) — The total number of pages.
- `total_results` (integer, required) — The total number of results.

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (map from string to any, optional)

### FilesetFilterName

Filter by fileset name.

### FilesetFilterDescription

Filter by fileset description.

### DatetimeFilter

- `$gte` (datetime, optional) — Filter for results greater than or equal to this datetime.
- `$lte` (datetime, optional) — Filter for results less than or equal to this datetime.

### FilesetOutputStorage

### FilesetMetadata

Tagged metadata container - the key indicates the type. Example: metadata = FilesetMetadata( dataset=DatasetMetadataContent( schema=\{"columns": \["id", "name"]}, ) )

- `dataset` (DatasetMetadataContent, optional) — Content for dataset-type filesets.
- `model` (ModelMetadataContent, optional) — Content for model-type filesets. Contains tool calling configuration that is merged into the ModelSpec during checkpoint analysis.
- `environment` (EnvironmentMetadataContent, optional) — Content for environment-type filesets (GRPO Gym packages).

### ValidationErrorLocItems

### StringFilter

- `$eq` (string, optional) — Filter for results equal to this value.
- `$like` (string, optional) — Filter for results matching this pattern.
- `$in` (list of string, optional) — Filter for results in this list of values.
- `$nin` (list of string, optional) — Filter for results not in this list of values.

### LocalStorageConfig

- `path` (string, required)
- `read_chunk_size` (integer, optional, default: 1048576) — Chunk size in bytes for reading/streaming files. Larger chunks reduce async overhead but increase memory per concurrent download. Default: 1MB.
- `type` ("local", optional, default: local)
- `write_buffer_size` (integer, optional, default: 16777216) — How many bytes to buffer before flushing to disk

### NGCStorageConfig

- `org` (string, required) — NGC organization name
- `team` (string, required) — NGC team name
- `target` (string, required) — NGC asset name (model or resource)
- `api_key_secret` (string, required) — NGC API key secret name
- `read_chunk_size` (integer, optional, default: 1048576) — Chunk size in bytes for reading/streaming files. Larger chunks reduce async overhead but increase memory per concurrent download. Default: 1MB.
- `type` ("ngc", optional, default: ngc)
- `target_type` (enum, optional, default: resource) — Type of NGC asset: 'resource' or 'model'
  - Allowed values: `resource`, `model`
- `version` (string, optional) — NGC asset version. If not provided, defaults to latest version
- `original_version` (string, optional) — The original version requested by the user before resolution (e.g., 'latest' or None). The 'version' field contains the resolved version ID.
- `host` (string, optional, default: https://api.ngc.nvidia.com) — NGC API host URL

### HuggingfaceStorageConfig

- `repo_id` (string, required) — Huggingface repository ID (e.g., 'meta-llama/Llama-2-7b')
- `read_chunk_size` (integer, optional, default: 1048576) — Chunk size in bytes for reading/streaming files. Larger chunks reduce async overhead but increase memory per concurrent download. Default: 1MB.
- `type` ("huggingface", optional, default: huggingface)
- `repo_type` (enum, optional, default: model) — Type of Huggingface repository: 'model', 'dataset', or 'space'
  - Allowed values: `model`, `dataset`, `space`
- `revision` (string, optional, default: main) — Branch, tag, or commit SHA. Defaults to 'main'
- `original_revision` (string, optional) — The original revision requested by the user before resolution (e.g., 'main'). The 'revision' field contains the resolved commit SHA.
- `token_secret` (string, optional) — Huggingface API `token` secret name for private repositories
- `endpoint` (string, optional, default: https://huggingface.co) — Huggingface Hub endpoint URL. Use for self-hosted instances.

### S3StorageConfig

- `bucket` (string, required) — S3 bucket name
- `read_chunk_size` (integer, optional, default: 1048576) — Chunk size in bytes for reading/streaming files. Larger chunks reduce async overhead but increase memory per concurrent download. Default: 1MB.
- `type` ("s3", optional, default: s3)
- `prefix` (string, optional, default: ) — Optional prefix (folder path) within the bucket. All operations will be relative to this prefix.
- `region` (string, optional) — AWS region. If not specified, uses SDK default (env vars, instance metadata, etc.)
- `endpoint_url` (string, optional) — Custom endpoint URL for S3-compatible storage (e.g., MinIO, Garage, RustFS). If not specified, uses AWS S3.
- `use_sdk_auth` (boolean, optional, default: false) — Use AWS SDK credential chain for authentication (env vars like AWS_ACCESS_KEY_ID, IAM roles, instance profiles, etc.). This option is only available for the platform's default storage backend. User-provided S3 storage must use explicit credentials via access_key_id_secret and secret_access_key_secret.
- `access_key_id_secret` (string, optional) — Secret reference for AWS access key ID. Requires use_sdk_auth=False.
- `secret_access_key_secret` (string, optional) — Secret reference for AWS secret access key. Requires use_sdk_auth=False.
- `signature_version` (enum, optional, default: s3v4) — AWS signature version for request signing. Use 's3' for legacy systems that only support signature v2.
  - Allowed values: `s3v4`, `s3`

### GithubStorageConfig

- `owner` (string, required) — GitHub repository owner (user or organization)
- `repo` (string, required) — GitHub repository name
- `read_chunk_size` (integer, optional, default: 1048576) — Chunk size in bytes for reading/streaming files. Larger chunks reduce async overhead but increase memory per concurrent download. Default: 1MB.
- `type` ("github", optional, default: github)
- `revision` (string, optional, default: HEAD) — Branch, tag, or commit SHA. 'HEAD' resolves to the repository's default branch.
- `original_revision` (string, optional) — The original revision requested by the user before resolution (e.g., 'main'). The 'revision' field contains the resolved commit SHA.
- `path` (string, optional, default: ) — Optional directory within the repository. All paths are relative to it.
- `token_secret` (string, optional) — GitHub personal access token secret name, required for private repositories
- `api_base_url` (string, optional, default: https://api.github.com) — GitHub API base URL. Use for GitHub Enterprise instances.

### DatasetMetadataContent

Content for dataset-type filesets.

- `schema` (DatasetMetadataContentSchema, optional) — Default row schema for files in this fileset, either inline JSON Schema or a schema_defs key.
- `schema_defs` (map from string to map from string to any, optional) — Reusable JSON Schema definitions keyed by name for deduplicating per-file dataset schemas.
- `schemas_by_path` (map from string to DatasetMetadataContentSchemasByPath, optional) — Optional per-file row schemas keyed by relative path within the fileset. Each value may be inline JSON Schema or a schema_defs key.

### ModelMetadataContent

Content for model-type filesets. Contains tool calling configuration that is merged into the ModelSpec during checkpoint analysis.

- `tool_calling` (ToolCallingMetadataContent, optional) — Content for tool-calling configuration on model filesets. Stores chat template and tool calling settings that are merged into the ModelSpec during checkpoint analysis.

### EnvironmentMetadataContent

Content for environment-type filesets (GRPO Gym packages).

- `format` (string, required) — Environment package format (native-v1, wheels-v1, adapter-wheels-v1).
- `name` (string, required)
- `adapter_agent` (string, optional)
- `hub_id` (string, optional)
- `vf_env_id` (string, optional)
- `config_paths` (list of string, optional)

### DatasetMetadataContentSchema

Default row schema for files in this fileset, either inline JSON Schema or a schema_defs key.

### DatasetMetadataContentSchemasByPath

### ToolCallingMetadataContent

Content for tool-calling configuration on model filesets. Stores chat template and tool calling settings that are merged into the ModelSpec during checkpoint analysis.

- `chat_template` (string, optional) — Jinja2 chat template for the model.
- `tool_call_parser` (string, optional) — Name of the tool call parser (e.g., 'openai', 'hermes', 'pythonic', 'llama3_json', 'mistral').
- `tool_call_plugin` (string, optional) — Reference to a fileset containing a custom tool call plugin Python file. Expected format: '\{workspace}/\{fileset\_name}'.
- `auto_tool_choice` (boolean, optional) — Whether to enable automatic tool choice.

## Examples

**Response**

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "workspace": "string",
      "description": "string",
      "purpose": "dataset",
      "storage": {
        "path": "string",
        "read_chunk_size": 1048576,
        "type": "local",
        "write_buffer_size": 16777216
      },
      "metadata": {
        "dataset": {
          "schema": {},
          "schema_defs": {},
          "schemas_by_path": {}
        },
        "model": {
          "tool_calling": {
            "chat_template": "string",
            "tool_call_parser": "string",
            "tool_call_plugin": "string",
            "auto_tool_choice": true
          }
        },
        "environment": {
          "format": "string",
          "name": "string",
          "adapter_agent": "string",
          "hub_id": "string",
          "vf_env_id": "string",
          "config_paths": [
            "string"
          ]
        }
      },
      "custom_fields": {},
      "project": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 1,
    "current_page_size": 1,
    "total_pages": 1,
    "total_results": 1
  },
  "sort": "string",
  "filter": {}
}
```

**SDK Code**

```python
import requests

url = "https://api.example.com/apis/files/v2/workspaces/workspace/filesets"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.example.com/apis/files/v2/workspaces/workspace/filesets';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/apis/files/v2/workspaces/workspace/filesets"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.example.com/apis/files/v2/workspaces/workspace/filesets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.example.com/apis/files/v2/workspaces/workspace/filesets")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.example.com/apis/files/v2/workspaces/workspace/filesets');

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/apis/files/v2/workspaces/workspace/filesets");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/apis/files/v2/workspaces/workspace/filesets")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```