Upload a file

POST/v3/documents/file

Upload a file to be processed

Body ParametersForm DataExpand Collapse

file: file

File to upload and process

containerTag: optional string

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

DeprecatedcontainerTags: optional string

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.

customId: optional string

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

maxLength100

entityContext: optional string

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

maxLength1500

filepath: optional string

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

fileType: optional string

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

filterByMetadata: optional string

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 string

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.

mimeType: optional string

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

taskType: optional "memory" or "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"

DeprecateduseAdvancedProcessing: optional string

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

id: string

Unique identifier of the document

status: string

Status of the document

Upload a file

curl https://api.supermemory.ai/v3/documents/file \
    -H 'Content-Type: multipart/form-data' \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
    -F 'file=@/path/to/file' \
    -F containerTag=user \
    -F customId=mem_abc123 \
    -F entityContext="User's name is {XYZ}" \
    -F filepath=/documents/reports/file.pdf \
    -F fileType=image \
    -F filterByMetadata='{"department": "engineering"}' \
    -F metadata='{"category": "technology", "isPublic": true, "readingTime": 5}' \
    -F taskType=memory \
    -F useAdvancedProcessing=true

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

Returns Examples

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