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

# Add Documents

> Import one or more Library files into a project as documents

```
POST /openapi/memorylake/api/v1/projects/{id}/documents
```

Imports files from the user's Library into a project. Each imported file becomes a project document and is queued for processing immediately. The operation is batch and supports **partial success** — the response tells you how many imports succeeded and how many failed.

You can pass either **file** or **directory** IDs in `drive_item_ids`. Directories are recursively flattened to every descendant file before import, so importing a folder effectively imports its whole subtree in one call. Unsupported item types inside a directory are silently skipped.

For convenience, `drive_item_ids` also accepts two aliases:

* `MY_SPACE` — import every file under the user's workspace root in one call.
* `ROOT` — import every file the user has access to across the whole Library.

To add a file that is not yet in the Library, upload it first using the [Library upload flow](/features/memorylake/api-reference/library/overview#uploading-a-file-end-to-end).

<Note>
  **Permissions required (all of):**

  * [`project:doc_add`](/features/team-collaboration/permission-reference#add-a-document-to-a-project) · `instance`
  * [`drive:item_read`](/features/team-collaboration/permission-reference#read-your-files) · `service`

  **Workflow note:** The two permissions above are checked together when this endpoint is called — `drive:item_read` is needed because the server resolves and reads each referenced drive item. If you're uploading a **new** file end-to-end first, the Library upload calls ([Create Upload](/features/memorylake/api-reference/library/create-upload) and [Create Item](/features/memorylake/api-reference/library/create-item)) additionally require [`drive:item_add`](/features/team-collaboration/permission-reference#upload-and-create-files).
</Note>

### Path Parameters

<ParamField path="id" type="string" required>
  Project ID.
</ParamField>

### Request Body

<ParamField body="drive_item_ids" type="array" required>
  Library item IDs to import. Accepts file and directory IDs in any combination — directories are recursively flattened to all descendant files, and unsupported item types are silently skipped. The aliases `MY_SPACE` (your workspace root) and `ROOT` (the whole Library) are also accepted.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v1/projects/proj-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6/documents' \
    -H 'Authorization: Bearer sk_xxxxxx' \
    -H 'Content-Type: application/json' \
    -d '{
      "drive_item_ids": [
        "sc-5c6bf0f82d624a20a6fa4696997bdd46:7d8cf1e93f634b31b5",
        "sc-5c6bf0f82d624a20a6fa4696997bdd46:2a8cf1e93f634b31b7"
      ]
    }'
  ```

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

  BASE = "https://app.memorylake.ai/openapi/memorylake/api/v1"
  HEADERS = {"Authorization": "Bearer sk_xxxxxx", "Content-Type": "application/json"}

  resp = requests.post(
      f"{BASE}/projects/proj-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6/documents",
      headers=HEADERS,
      json={
          "drive_item_ids": [
              "sc-5c6bf0f82d624a20a6fa4696997bdd46:7d8cf1e93f634b31b5",
              "sc-5c6bf0f82d624a20a6fa4696997bdd46:2a8cf1e93f634b31b7",
          ]
      },
  ).json()

  print(f"imported {resp['data']['success_count']}, failed {resp['data']['failure_count']}")
  ```
</RequestExample>

### Response

<ResponseField name="data" type="object">
  <Expandable title="Batch create result">
    <ResponseField name="success_count" type="integer">Number of files successfully imported as documents</ResponseField>
    <ResponseField name="failure_count" type="integer">Number of files that failed to import</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true,
    "data": {
      "success_count": 2,
      "failure_count": 0
    }
  }
  ```
</ResponseExample>

<Note>
  After import, documents start out with status `pending` and transition through `running` → `okay` (or `error`). Poll [List Documents](/features/memorylake/api-reference/memories/list-documents) or [Get Document](/features/memorylake/api-reference/memories/get-document) to observe progress.
</Note>

## Typical Flow

<Steps>
  <Step title="Put the file in the Library">
    Either upload it via the [chunked upload flow](/features/memorylake/api-reference/library/overview#uploading-a-file-end-to-end), or locate an existing file with [List Items](/features/memorylake/api-reference/library/list-items).
  </Step>

  <Step title="Call Add Documents">
    Pass one or more `item_id`s inside `drive_item_ids`. You can mix files and directories — passing a directory imports every descendant file in one call. Batch in a single request when you can; it is faster than looping.
  </Step>

  <Step title="Track processing status">
    Poll [List Documents](/features/memorylake/api-reference/memories/list-documents) until the new documents reach `okay`.
  </Step>
</Steps>