files

Classes

FileMeta

Bases: BaseModel

Metadata information for a file.

This model is flexible and allows extra fields, but defines common metadata fields used by the system.

Returned by:

• Code Reference models files Classes FileModelResponse Attributes meta

Attributes

name

name: Optional[str] = None

Original name of the file.

content_type

content_type: Optional[str] = None

MIME type of the file (e.g., 'application/pdf', 'image/png').

size

size: Optional[int] = None

Size of the file in bytes.

FileModelResponse

Bases: BaseModel

Response model for file operations, containing file details and metadata.

Returned by:

• Code Reference routers files Classes FilesClient Functions
  • list_files
  • search_files
  • upload_file

Attributes

id

id: str

Unique identifier for the file.

user_id

user_id: str

ID of the user who uploaded or owns the file.

hash

hash: Optional[str] = None

MD5 or other hash of the file content for integrity verification.

filename

filename: str

Name of the file as stored in the system (often UUID prefixed).

data

data: Optional[dict] = None

Additional data associated with the file, such as processing status or extracted content.

Dict Fields

• status (str, optional): Processing status of the file - 'pending', 'completed', or 'failed'
• error (str, optional): Error message if file processing failed
• content (str, optional): Extracted text content from the file

The data dictionary stores file processing metadata and content. During file upload, the status starts as 'pending', changes to 'completed' when processing succeeds, or 'failed' with an error message when processing fails. The content field contains the extracted text from the file after successful processing.

meta

meta: FileMeta

Metadata about the file including original name, size, and content type.

created_at

created_at: int

Unix timestamp when the file was created.

updated_at

updated_at: int

Unix timestamp when the file was last updated.

FileMetadataResponse

Bases: BaseModel

Simplified response model focusing on file metadata.

Returned by:

• Code Reference models knowledge Classes
  • KnowledgeFilesResponse Attributes files
  • KnowledgeResponse Attributes files
  • KnowledgeUserResponse Attributes files

Attributes

id

id: str

Unique identifier for the file.

hash

hash: Optional[str] = None

File content hash.

meta

meta: Optional[dict] = None

File metadata dictionary.

Dict Fields

• name (str, optional): Original name of the file
• content_type (str, optional): MIME type of the file (e.g., 'application/pdf', 'image/png')
• size (int, optional): Size of the file in bytes
• data (dict, optional): Additional metadata associated with the file

created_at

created_at: int

Unix timestamp when the file was created.

updated_at

updated_at: int

Unix timestamp when the file was last updated.

FileModel

Bases: BaseModel

Complete internal representation of a file in the system.

Returned by:

• Code Reference
  • routers files Classes FilesClient Functions get_file_by_id
  • models retrieval Classes BatchProcessFilesForm Attributes files

Attributes

id

id: str

Unique identifier for the file.

user_id

user_id: str

ID of the user who owns the file.

hash

hash: Optional[str] = None

File content hash.

filename

filename: str

Name of the file as stored.

path

path: Optional[str] = None

Physical path or storage reference for the file content.

data

data: Optional[dict] = None

Additional data associated with the file, including processing status and extracted content.

Dict Fields

• status (str, optional): Processing status of the file - 'pending', 'completed', or 'failed'
• error (str, optional): Error message if file processing failed
• content (str, optional): Extracted text content from the file

meta

meta: Optional[dict] = None

File metadata containing information about the file.

Dict Fields

• name (str, optional): Original name of the file as uploaded
• content_type (str, optional): MIME type of the file (e.g., 'application/pdf', 'image/png', 'text/plain')
• size (int, optional): Size of the file in bytes
• data (dict, optional): Additional metadata associated with the file, can contain custom key-value pairs
• collection_name (str, optional): Knowledge base collection name this file belongs to, used for access control

The meta dictionary stores core file attributes and can be extended with additional custom metadata. Common usage includes file identification, content type handling, and knowledge base association.

access_control

access_control: Optional[dict] = None

Access control rules for the file.

Dict Fields

• read (dict, optional): Read access permissions
  • group_ids (list[str], optional): List of group IDs that have read access
  • user_ids (list[str], optional): List of user IDs that have read access
• write (dict, optional): Write access permissions
  • group_ids (list[str], optional): List of group IDs that have write access
  • user_ids (list[str], optional): List of user IDs that have write access

Controls which users and groups can read or write to the file. If None, access follows default system permissions.

created_at

created_at: Optional[int]

Unix timestamp when the file was created.

updated_at

updated_at: Optional[int]

Unix timestamp when the file was last updated.

ContentForm

Bases: BaseModel

Form for updating file content text.

Attributes

content

content: str

The new text content for the file.