> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload File

> Upload a document to be processed and stored in the agent's session namespace.

## Overview

Uploads a file into the agent’s Moorcheh namespace for the active session. Moorcheh extracts text and indexes it so content can be discovered via [Recall](/api-reference/search/recall).

<Note>
  Supported extensions: `.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md`. The route validates the extension before upload. Files are streamed to disk in 1 MB chunks and hard-capped at **5 GB**; anything larger is rejected mid-upload with `413`.
</Note>

## Authentication

API clients do not send an API key or `Authorization` header.

<ParamField header="X-Session-Token" type="string" required>
  Session token from [Activate Agent](/api-reference/sessions/activate-agent). Must match `agent_id`.
</ParamField>

When using **curl** with `-F`, do **not** set `Content-Type` manually — curl sets `multipart/form-data` with the correct boundary.

## Path Parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the agent.
</ParamField>

## Body (multipart)

<ParamField body="file" type="file" required>
  File field name must be **`file`** (FastAPI `UploadFile` parameter).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8000/api/v2/agents/my-agent/upload-file" \
    -H "X-Session-Token: your_session_token" \
    -F "file=@report.pdf"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "agent_id": "my-agent",
    "session_id": "session_abc123",
    "namespace": "memanto_agent_my-agent",
    "file_name": "quarterly-report.pdf",
    "file_size": 2516582,
    "status": "uploaded",
    "message": ""
  }
  ```

  ```json 400 - Bad Request (Unsupported File Type) theme={null}
  {
    "detail": "File type '.exe' is not supported. Allowed types: .csv, .docx, .json, .md, .pdf, .txt, .xlsx"
  }
  ```

  ```json 401 - Unauthorized (Missing Token) theme={null}
  {
    "detail": "Missing session token. Use X-Session-Token header."
  }
  ```

  ```json 401 - Unauthorized (Expired Token) theme={null}
  {
    "detail": {
      "error": "SessionExpired",
      "message": "Session has expired",
      "details": {}
    }
  }
  ```

  ```json 422 - Validation Error (Missing File) theme={null}
  {
    "detail": [
      {
        "type": "missing",
        "loc": ["body", "file"],
        "msg": "Field required",
        "input": {}
      }
    ]
  }
  ```

  ```json 413 - Payload Too Large (File Exceeds 5 GB) theme={null}
  {
    "detail": {
      "error": "file_too_large",
      "message": "File exceeds the maximum upload size of 5 GB",
      "max_bytes": 5368709120
    }
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "detail": {
      "error": "InternalServerError",
      "message": "An unexpected error occurred",
      "details": {
        "original_error": "Session is for agent 'other-agent', cannot access 'my-agent'"
      }
    }
  }
  ```
</ResponseExample>

## Next Steps

* [Recall](/api-reference/search/recall) to search across uploaded content
* [Remember](/api-reference/data/remember) to add structured memories alongside uploads