File Manager - API Reference

All Services byoc mlflow rag_input

RAG Input File Management API (1.0.0)

Download OpenAPI specification:

RAG Input file management endpoints. Handles upload and management of binary media files for RAG (Retrieval-Augmented Generation). A file may be placed in a scope (an ordered folder path, e.g. project/module); an empty scope means a plain database-level file. Files support versioning — each upload of the same file (identified by name + database + scope) creates a new version.

Supported file types: images, videos, audio, PDFs, and other binary media.

Limits (for product/UX awareness):

  • Scope depth: a scope can have at most 5 levels (labels).
  • Scope label: each label allows only letters, digits, hyphen and underscore, up to 128 characters.
  • Scope total: all labels of one scope combined must be at most 256 characters.
  • File name: 1 to 255 characters.
  • File size: a single upload has no service-enforced size limit (a gateway/proxy may still cap the request).
  • Batch: at most 100 files and 2 GiB total per request (the size check runs after the whole request body is received).
  • List: limit 1–1000 (default 100), offset >= 0; search is a case-insensitive substring on the name; a scope filter returns that scope and everything below it; only the latest version of each file is listed.
  • Browse: child scopes and their active-file counts come from a single registry read; each scope also returns the files uploaded exactly at that scope (children and files together, not either/or).
  • Versions: re-uploading the same name + scope keeps adding versions (version history is not capped).
  • Custom metadata: optional string→string map on upload (at most 32 keys; key ≤64 chars; value ≤2048 chars; total serialized size ≤16 KiB). Opaque to File Manager — stored and returned as given.

RAG Input Files

Upload a RAG input file

Uploads a binary file for RAG processing. Stores the file in StorageSidecar and creates metadata in MetadataStoreSidecar. Each upload of the same file (name + database + scope) creates a new version. Optional custom_metadata is a JSON object of string keys/values stored with the file and returned on get/list (replaced on each new version).

path Parameters
database
required
string

Database name

Request Body schema: multipart/form-data
required
name
required
string [ 1 .. 255 ] characters

File name identifier

scope
Array of strings (ScopeSegment) <= 5 items [ items [ 1 .. 128 ] characters ^[A-Za-z0-9_-]+$ ]
Default: []

Ordered scope labels addressing the file within the database (e.g. [project, module]). Labels combined must not exceed 256 characters. Empty = default/legacy file.

file
required
string <binary>

File content to upload

custom_metadata
string

Optional JSON object of string keys/values (e.g. {"author":"Ada","citable_url":"https://example.com"}). Opaque to File Manager; stored with the file and returned on get/list. At most 32 keys; key ≤64 chars; value ≤2048 chars; total serialized size ≤16 KiB. Omitted or empty = {}.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "database": "string",
  • "scope": [ ],
  • "content_type": "string",
  • "size": 0,
  • "uploaded_at": "2019-08-24T14:15:22Z",
  • "metadata_key": "string",
  • "version": 1,
  • "safe_to_delete": true,
  • "custom_metadata": { }
}

List RAG input files

Lists RAG input files for a database, returning only the latest version of each file (one entry per file id). Optionally filtered by scope (this scope and below; empty = whole database), by exact file name, or by a case-insensitive substring search on the file name.

path Parameters
database
required
string

Database name

query Parameters
name
string

Filter by exact file name

search
string

Case-insensitive substring match on the file name (UI search box). Combines with scope and pagination.

scope
Array of strings (ScopeSegment) <= 5 items [ items [ 1 .. 128 ] characters ^[A-Za-z0-9_-]+$ ]

Ordered scope labels; returns files at this scope and below (e.g. scope=acme&scope=legal). Omit the parameter to search the entire database; supply it to search that scope and its subtree. Labels combined must not exceed 256 characters. Only the latest version of each file is returned.

limit
integer [ 1 .. 1000 ]
Default: 100

Maximum number of results

offset
integer >= 0
Default: 0

Pagination offset

Responses

Response samples

Content type
application/json
{
  • "files": [
    • {
      • "id": "string",
      • "name": "string",
      • "database": "string",
      • "scope": [ ],
      • "content_type": "string",
      • "storage_location": "string",
      • "size": 0,
      • "uploaded_at": "2019-08-24T14:15:22Z",
      • "version": 1,
      • "safe_to_delete": true,
      • "custom_metadata": { }
      }
    ],
  • "total": 0,
  • "limit": 1,
  • "offset": 0
}

Upload many files in one request

Upload several files at once, each placed under its own scope. Use for a folder / multi-category upload.

Two ways to say where each file goes:

  • manifest: a JSON array (one entry per file) giving each file its own scope and optional name. Entries pair with files by an explicit file index, or by list order. Best for a UI submitting several categories at once.
  • shared scope + mapping: every file uses scope; with mapping=preserve_paths the subfolders in each upload's filename become extra scope levels (a folder upload).

Each file is processed independently: a bad file is reported as an error and does not stop the others. Max 100 files and 2 GiB total per request.

Status codes: 200 when all files succeed; 207 when the request was processed but one or more files failed (per-file results in the body); 500 when every file fails with an internal error (e.g. the storage backend is down); 400/413 for a malformed or oversized request.

path Parameters
database
required
string

Database name

Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> [ items <binary > ]

One or more files to upload

manifest
string

Optional JSON array, one entry per file: [{"file": 0, "scope": ["acme","legal"], "name": "a.pdf", "custom_metadata": {"author": "Ada"}}]. Each entry's scope follows the common scope limits. Optional per-entry custom_metadata is a string→string object (same limits as single-file upload), merged on top of the shared custom_metadata form field (entry value wins on a key collision).

scope
Array of strings (ScopeSegment) <= 5 items [ items [ 1 .. 128 ] characters ^[A-Za-z0-9_-]+$ ]
Default: []

Shared ordered scope for all files when no manifest is supplied. Labels combined must not exceed 256 characters.

mapping
string
Default: "flatten"
Enum: "flatten" "preserve_paths"

How to place files when using the shared scope. 'flatten' puts all files directly under scope; 'preserve_paths' appends each file's subfolders as extra scope levels.

custom_metadata
string

Optional JSON object of string keys/values applied to every file in the batch. A manifest entry's own custom_metadata is merged on top (entry value wins on a key collision).

Responses

Response samples

Content type
application/json
{
  • "database": "string",
  • "results": [
    • {
      • "name": "string",
      • "scope": [ ],
      • "status": "string",
      • "id": "string",
      • "version": 1,
      • "content_type": "string",
      • "size": 0,
      • "uploaded_at": "2019-08-24T14:15:22Z",
      • "metadata_key": "string",
      • "custom_metadata": { },
      • "detail": "string"
      }
    ],
  • "ok_count": 0,
  • "error_count": 0
}

Get version history for a file

Get the full version history for a specific file lineage. A lineage is identified by name + database + scope (empty scope = a default/database-level file).

path Parameters
database
required
string

Database name

query Parameters
name
required
string

File name identifier

scope
Array of strings (ScopeSegment) <= 5 items [ items [ 1 .. 128 ] characters ^[A-Za-z0-9_-]+$ ]

Ordered scope labels identifying the lineage (same scope used at upload). Labels combined must not exceed 256 characters. Empty = a default/database-level file.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "database": "string",
  • "scope": [ ],
  • "versions": [
    • {
      • "version": 1,
      • "metadata_key": "string"
      }
    ],
  • "latest_version": 1
}

Browse a scope (children and files)

Browse one level of the scope tree. Returns the immediate child scopes (e.g. the modules in a project) AND the files located exactly at the given scope — both in the same response (not either/or). On a project page (scope=[project]) that means modules in children plus any files uploaded directly to the project in files. Children come from a per-(database, parent-scope) registry (a single read); files at the exact scope come from a prefix scan.

path Parameters
database
required
string

Database name

query Parameters
scope
Array of strings (ScopeSegment) <= 5 items [ items [ 1 .. 128 ] characters ^[A-Za-z0-9_-]+$ ]

The scope path to browse (e.g. scope=acme for a project page). Labels combined must not exceed 256 characters. Empty = the database root (lists top-level scopes).

Responses

Response samples

Content type
application/json
{
  • "database": "string",
  • "scope": [ ],
  • "children": [
    • {
      • "segment": "string",
      • "file_count": 0
      }
    ],
  • "files": [
    • {
      • "id": "string",
      • "name": "string",
      • "database": "string",
      • "scope": [ ],
      • "content_type": "string",
      • "storage_location": "string",
      • "size": 0,
      • "uploaded_at": "2019-08-24T14:15:22Z",
      • "version": 1,
      • "safe_to_delete": true,
      • "custom_metadata": { }
      }
    ]
}

Get RAG input file information

Retrieves metadata and information about a stored RAG input file.

path Parameters
database
required
string

Database name

id
required
string

File identifier

query Parameters
version
integer >= 1

Version number (default: latest)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "database": "string",
  • "scope": [ ],
  • "content_type": "string",
  • "storage_location": "string",
  • "size": 0,
  • "uploaded_at": "2019-08-24T14:15:22Z",
  • "version": 1,
  • "safe_to_delete": true,
  • "custom_metadata": { }
}

Set the safe-to-delete flag for a file

Set or clear safe_to_delete for a file (the whole lineage — all versions). Consumer services use this to lock a file while it is in use (false) and unlock it when it may be removed (true). Delete is gated on this flag.

path Parameters
database
required
string

Database name

id
required
string

File identifier

Request Body schema: application/json
required
safe_to_delete
required
boolean

Whether the file may be deleted (true = unlocked)

Responses

Request samples

Content type
application/json
{
  • "safe_to_delete": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "database": "string",
  • "scope": [ ],
  • "content_type": "string",
  • "storage_location": "string",
  • "size": 0,
  • "uploaded_at": "2019-08-24T14:15:22Z",
  • "version": 1,
  • "safe_to_delete": true,
  • "custom_metadata": { }
}

Delete a RAG input file

Deletes a RAG input file from StorageSidecar and removes its metadata from MetadataStoreSidecar.

path Parameters
database
required
string

Database name

id
required
string

File identifier

query Parameters
version
integer >= 1

Version number (default: latest)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "database": "string",
  • "status": "deleted"
}

Delete multiple files by id

Delete several files in one request, each given by its file id. Each id deletes the WHOLE file (all versions). Only files with safe_to_delete=true are removed; locked files are reported and left untouched. Per-file results.

path Parameters
database
required
string

Database name

Request Body schema: application/json
required
ids
required
Array of strings [ 1 .. 100 ] items

File ids to delete (each removes the whole file)

Responses

Request samples

Content type
application/json
{
  • "ids": [
    • "string"
    ]
}

Response samples

Content type
application/json
{
  • "database": "string",
  • "results": [
    • {
      • "id": "string",
      • "status": "string",
      • "detail": "string"
      }
    ],
  • "deleted_count": 0,
  • "locked_count": 0,
  • "error_count": 0
}

Delete all files under a scope (module)

Delete every file at the given scope AND below it (subtree) — e.g. a whole module. Only files with safe_to_delete=true are removed; locked files are reported and left untouched. An empty scope is rejected so the whole database cannot be wiped by accident.

path Parameters
database
required
string

Database name

Request Body schema: application/json
required
scope
required
Array of strings (ScopeSegment) <= 5 items [ items [ 1 .. 128 ] characters ^[A-Za-z0-9_-]+$ ]

Non-empty scope whose files and sub-scopes to delete; labels combined must not exceed 256 characters

Responses

Request samples

Content type
application/json
{
  • "scope": [
    • "string"
    ]
}

Response samples

Content type
application/json
{
  • "database": "string",
  • "scope": [
    • "string"
    ],
  • "deleted": [
    • "string"
    ],
  • "locked": [
    • "string"
    ],
  • "failed": [
    • "string"
    ],
  • "deleted_count": 0,
  • "locked_count": 0
}

Set the safe-to-delete flag for many files (by id)

Set safe_to_delete (the whole lineage — all versions) for several files in one request. Consumer services use this to lock files while in use (false) and unlock them (true). Unknown ids are reported as not_found.

path Parameters
database
required
string

Database name

Request Body schema: application/json
required
ids
required
Array of strings [ 1 .. 100 ] items

File ids whose safe_to_delete flag to set (whole lineage each)

safe_to_delete
required
boolean

New flag value (false = lock, true = unlock)

Responses

Request samples

Content type
application/json
{
  • "ids": [
    • "string"
    ],
  • "safe_to_delete": true
}

Response samples

Content type
application/json
{
  • "database": "string",
  • "results": [
    • {
      • "id": "string",
      • "status": "string"
      }
    ],
  • "updated_count": 0,
  • "error_count": 0
}

Set the safe-to-delete flag for all files under a scope (module)

Set safe_to_delete for every file at the given scope AND below it (subtree) — e.g. a whole module. An empty scope is rejected so the whole database cannot be toggled by accident.

path Parameters
database
required
string

Database name

Request Body schema: application/json
required
scope
required
Array of strings (ScopeSegment) <= 5 items [ items [ 1 .. 128 ] characters ^[A-Za-z0-9_-]+$ ]

Non-empty scope whose files and sub-scopes to update; labels combined must not exceed 256 characters

safe_to_delete
required
boolean

New flag value (false = lock, true = unlock)

Responses

Request samples

Content type
application/json
{
  • "scope": [
    • "string"
    ],
  • "safe_to_delete": true
}

Response samples

Content type
application/json
{
  • "database": "string",
  • "scope": [
    • "string"
    ],
  • "updated": [
    • "string"
    ],
  • "failed": [
    • "string"
    ],
  • "updated_count": 0
}

Download a RAG input file

Downloads the actual file content as a streaming binary response.

path Parameters
database
required
string

Database name

id
required
string

File identifier

query Parameters
version
integer >= 1

Version number (default: latest)

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}