File Management

Files serve as the foundation for all content processing workflows in Mixedbread. They provide secure upload, storage, and retrieval of documents with support for various file types including PDFs, images, and structured data. Manage files within your stores with version management, metadata support, and unique ID referencing.

Upload FilesLink to section

CommandLink to section

mxbai store upload <name-or-id> <patterns...> [options]

OptionsLink to section

--strategy fast|high_quality - Processing strategy (default: fast)
--contextualization - Deprecated: Now configured at store level using mxbai store create --contextualization. This flag is ignored and will be removed in a future version.
--metadata <json> - JSON metadata for uploaded files
--dry-run - Preview what would be uploaded without uploading
--parallel <n> - Number of concurrent uploads (default: 100, range: 1 - 200)
--unique - Update existing files instead of creating duplicates
--manifest <file> - Upload using manifest file
--multipart-threshold <mb> - File size threshold in MB to trigger multipart upload
--multipart-part-size <mb> - Size of each part in MB for multipart upload
--multipart-concurrency <n> - Number of concurrent part uploads for multipart upload

Manifest File FormatLink to section

The manifest file allows you to define complex upload configurations with different settings for different file patterns. Both JSON (.json) and YAML (.yaml or .yml) formats are supported.

JSON format:

{
  "version": "1.0",
  "defaults": {
    "strategy": "fast",
    // "contextualization": false, // Deprecated - now configured at store level
    "metadata": {
      "project": "my-project"
    }
  },
  "files": [
    {
      "path": "docs/**/*.md",
      "metadata": {
        "category": "documentation"
      }
    },
    {
      "path": "README.md",
      "strategy": "high_quality",
      // contextualization is deprecated - configure at store level instead
      "metadata": {
        "importance": "high"
      }
    }
  ]
}

YAML format:

version: "1.0"

defaults:
  strategy: fast
  # contextualization: false # Deprecated - now configured at store level
  metadata:
    project: my-project

files:
  - path: "docs/**/*.md"
    metadata:
      category: documentation
  - path: README.md
    strategy: high_quality
    # contextualization is deprecated - configure at store level instead
    metadata:
      importance: high

Manifest properties:

version - Manifest format version (currently "1.0")
defaults - Default settings applied to all files
- strategy - Default processing strategy
- contextualization - (Deprecated) Include metadata in chunk embeddings to improve search relevance - now configured at store level
- metadata - Default metadata for all files
files - Array of file upload configurations
- path - Glob pattern for files to upload
- strategy - Specific strategy for this pattern
- contextualization - (Deprecated) Contextualization for this pattern - now configured at store level
- metadata - Additional metadata for this pattern (merged with defaults)

ExamplesLink to section

# Upload markdown files
mxbai store upload "my-knowledge-base" "*.md"

# Upload multiple file types
mxbai store upload "my-knowledge-base" "*.md" "docs/**/*.pdf"

# Upload with high quality processing
mxbai store upload "my-knowledge-base" "*.pdf" --strategy high_quality

# Deprecated: contextualization is now configured at the store level
# mxbai store upload "my-knowledge-base" "*.md" --contextualization

# Upload with metadata
mxbai store upload "my-knowledge-base" "*.md" --metadata '{"category": "docs"}'

# Dry run to preview upload
mxbai store upload "my-knowledge-base" "*.md" --dry-run

# Upload with manifest file (JSON or YAML)
mxbai store upload "my-knowledge-base" --manifest upload-manifest.json
mxbai store upload "my-knowledge-base" --manifest upload-manifest.yaml

# Upload large files with multipart upload
mxbai store upload "my-knowledge-base" "*.pdf" \
  --multipart-threshold 50 \
  --multipart-part-size 25 \
  --multipart-concurrency 10

Upload Summary InformationLink to section

The upload command displays strategy information in the summary after completion:

✓ 5 files uploaded successfully
Strategy: fast
Total size: 25.3 KB

For manifest uploads, configuration is shown beside each file:

✓ docs/api.md (15.2 KB) [fast]
✓ README.md (8.5 KB) [high_quality]
✓ guide.md (1.6 KB) [fast]

This allows you to see exactly which strategy was applied to each file, making it easy to verify that your manifest configuration is working as expected.

List FilesLink to section

CommandLink to section

mxbai store files list <name-or-id> [options]

Alias: mxbai store files ls <name-or-id>

OptionsLink to section

--status <status> - Filter by status: pending, in_progress, cancelled, completed, failed
--limit <n> - Limit number of results

ExamplesLink to section

# List all files in store
mxbai store files list "my-knowledge-base"

# List using alias
mxbai store files ls "my-knowledge-base"

# List only completed files
mxbai store files list "my-knowledge-base" --status completed

# List with limit
mxbai store files list "my-knowledge-base" --limit 50

# List failed files for troubleshooting
mxbai store files list "my-knowledge-base" --status failed

Get File DetailsLink to section

CommandLink to section

mxbai store files get <name-or-id> <file-id>

OptionsLink to section

None

ExamplesLink to section

# Get details of a specific file
mxbai store files get "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479"

# Get file details using store ID
mxbai store files get "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012"

Delete FileLink to section

CommandLink to section

mxbai store files delete <name-or-id> <file-id> [options]

Alias: mxbai store files rm <name-or-id> <file-id>

OptionsLink to section

--yes, -y - Skip confirmation prompt

ExamplesLink to section

# Delete file with confirmation
mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479"

# Delete file without confirmation
mxbai store files delete "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes

# Delete using alias
mxbai store files rm "my-knowledge-base" "f47ac10b-58cc-4372-a567-0e02b2c3d479" --yes

# Delete from store by ID
mxbai store files delete "my-knowledge-base" "b2c3d4e5-f6a7-8901-bcde-f23456789012" --yes

File Management

On this page