Upload a file

documents.upload_file() -> DocumentUploadFileResponse

POST/v3/documents/file

Upload a file to be processed

ParametersExpand Collapse

file: FileTypes

File to upload and process

container_tag: Optional[str]

Optional container tag (e.g., ‘user_123’). Use this for a single tag.

Deprecatedcontainer_tags: Optional[str]

Optional container tags. Can be either a JSON string of an array (e.g., ’[“user_123”, “project_123”]’) or a single string (e.g., ‘user_123’). Single strings will be automatically converted to an array.

custom_id: Optional[str]

Optional custom ID of the document. Max 100 characters, alphanumeric with hyphens, underscores, and colons only.

maxLength100

entity_context: Optional[str]

Optional entity context for this container tag. Max 1500 characters. Used during document processing to guide memory extraction.

maxLength1500

filepath: Optional[str]

Optional file path for the uploaded file (e.g., ‘/documents/reports/file.pdf’). Used by supermemoryfs to map documents to filesystem paths.

file_type: Optional[str]

Optional file type override to force specific processing behavior. Valid values: text, pdf, tweet, google_doc, google_slide, google_sheet, image, video, notion_doc, webpage, onedrive

filter_by_metadata: Optional[str]

Optional metadata filter as a JSON string. Scopes which existing memories are pulled as context during ingestion. Scalar values match exactly (AND across keys); array values match ANY (OR within key).

metadata: Optional[str]

Optional metadata for the document as a JSON string. This is used to store additional information about the document. Keys must be strings and values can be strings, numbers, or booleans.

mime_type: Optional[str]

Required when fileType is ‘image’ or ‘video’. Specifies the exact MIME type to use (e.g., ‘image/png’, ‘image/jpeg’, ‘video/mp4’, ‘video/webm’)

task_type: Optional[Literal["memory", "superrag"]]

Task type: “memory” (default) for full context layer with SuperRAG built in, “superrag” for managed RAG as a service.

One of the following:

"memory"

"superrag"

Deprecateduse_advanced_processing: Optional[str]

DEPRECATED: This field is no longer used. Advanced PDF processing is now automatic with our hybrid Mistral OCR + Gemini pipeline. This parameter will be accepted but ignored for backwards compatibility.

ReturnsExpand Collapse

class DocumentUploadFileResponse: …

id: str

Unique identifier of the document

status: str

Status of the document

Upload a file

import os
from supermemory import Supermemory

client = Supermemory(
    api_key=os.environ.get("SUPERMEMORY_API_KEY"),  # This is the default and can be omitted
)
response = client.documents.upload_file(
    file=b"Example data",
)
print(response.id)

{
  "id": "id",
  "status": "status"
}

Returns Examples

{
  "id": "id",
  "status": "status"
}