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

# Upload Document

> Upload a document for memory extraction

Upload a document for memory extraction. The response confirms that processing has started; memories may take a short time to become recallable.

<ParamField body="file" type="file" required>
  The document file to upload. Text files are limited to 10MB. PDFs are limited to 20MB.
</ParamField>

<ParamField body="user_name" type="string" required>
  Your name for generating first-person memory narratives.
</ParamField>

<ParamField body="item_id" type="string">
  Optional unique identifier for this document. Auto-generated if not provided.
  May contain word characters plus `-`, `_`, `=`, `!`, and `:`. Max 500 characters.
</ParamField>

<ParamField body="source_type" type="string">
  Document type hint for extraction and access control. See [Source Types](/reference/source-types).
</ParamField>

<RequestExample>
  ```bash curl theme={null}
  curl -X POST https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memorize \
    -H "x-api-key: $ENGRAMME_API_KEY" \
    -F "file=@meeting-notes.txt" \
    -F "user_name=John Doe" \
    -F "item_id=meeting-2025-01-15" \
    -F "source_type=text"
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memorize",
      headers={"x-api-key": os.environ["ENGRAMME_API_KEY"]},
      files={"file": open("meeting-notes.txt", "rb")},
      data={
          "user_name": "John Doe",
          "item_id": "meeting-2025-01-15",
          "source_type": "text"
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.ENGRAMME_API_KEY;
  const formData = new FormData();
  formData.append('file', new Blob(['Meeting notes'], { type: 'text/plain' }), 'meeting-notes.txt');
  formData.append('user_name', 'John Doe');
  formData.append('item_id', 'meeting-2025-01-15');
  formData.append('source_type', 'text');

  const response = await fetch(
    'https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memorize',
    {
      method: 'POST',
      headers: { 'x-api-key': apiKey },
      body: formData
    }
  );
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": "success",
    "user_id": "user_abc123",
    "item_id": "meeting-2025-01-15",
    "workflow_execution": "projects/engramme/locations/us-central1/workflows/realtime-memory-pipeline/executions/exec-abc123"
  }
  ```

  ```json 400 theme={null}
  {
    "detail": "File must be valid UTF-8 encoded text"
  }
  ```

  ```json 401 theme={null}
  {
    "detail": "UNAUTHORIZED: API key not valid. Please pass a valid API key."
  }
  ```

  ```json 409 theme={null}
  {
    "detail": "Item ID 'meeting-2025-01-15' already exists or is currently being processed"
  }
  ```
</ResponseExample>

## Processing

`workflow_execution` is a backend processing reference. Most clients do not need to call it directly.

If you provide an `item_id`, the API may return `409` while the same item is currently being processed. Use stable unique IDs when you want deduplication; omit `item_id` for simple uploads.