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

# Create Fileset

POST /apis/files/v2/workspaces/{workspace}/filesets
Content-Type: application/json

Create a new fileset.

If no storage configuration is provided, the default storage backend will be used.

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

## Request

### Path parameters

- `workspace` (string, required)

### Body (application/json)

This endpoint expects a CreateFilesetRequest.

- `name` (string, required) — The name of the fileset. Name must start with a lowercase letter, be 2-63 characters, and use lowercase letters, digits, hyphens, and dots (no consecutive hyphens, cannot end with a hyphen).
- `description` (string, optional) — The description of the fileset.
- `project` (string, optional) — The name of the project associated with this fileset.
- `storage` (CreateFilesetRequestStorage, optional) — The storage configuration for the fileset. If not provided, uses default storage.
- `purpose` (enum, optional, default: generic) — The purpose of the fileset.
  - Allowed values: `dataset`, `environment`, `generic`, `model`
- `metadata` (FilesetMetadata, optional) — Purpose-specific metadata. Use the purpose as the key (e.g., \{dataset: \{...}}).
- `custom_fields` (map from string to any, optional) — Custom fields for the fileset.
- `cache` (boolean, optional, default: false) — Cache all files after creation. Only applies to external storage.

## Response

### 200

Successful Response

- `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)

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### CreateFilesetRequestStorage

The storage configuration for the fileset. If not provided, uses default storage.

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

### FilesetOutputStorage

### ValidationError

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

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

### ValidationErrorLocItems

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

**Request**

```json
{
  "name": "training-data-v1"
}
```

**Response**

```json
{
  "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"
}
```

**SDK Code**

```python
import requests

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

payload = { "name": "training-data-v1" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.example.com/apis/files/v2/workspaces/workspace/filesets';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"name":"training-data-v1"}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"name\": \"training-data-v1\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	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::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"training-data-v1\"\n}"

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.post("https://api.example.com/apis/files/v2/workspaces/workspace/filesets")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"training-data-v1\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.example.com/apis/files/v2/workspaces/workspace/filesets', [
  'body' => '{
  "name": "training-data-v1"
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"training-data-v1\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["name": "training-data-v1"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

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 = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```