> ## 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.

# Create Item

> Create a folder, or register a file after uploading its chunks

```
POST /openapi/memorylake/api/v1/drives/items
```

One endpoint, two modes — the `item_type` field selects which:

* **Folder** (`item_type: "folder"`) — creates an empty folder in the Library.
* **File** (`item_type: "file"`) — registers a file whose bytes are already in storage from a completed chunked upload. You must have called [Create Upload](/features/memorylake/api-reference/library/create-upload) first and collected every chunk's `ETag`.

Pick the tab below that matches the item type you're creating. Required fields differ by mode.

<Note>
  `parent_item_id` accepts the alias `MY_SPACE` (your workspace root). Pass it directly instead of looking up the root ID. You can also pass any folder's `item_id` to nest deeper.
</Note>

<Note>
  **Permission required:** [`drive:item_add`](/features/team-collaboration/permission-reference#upload-and-create-files) · `service`

  **Workflow note (file mode):** Calling this in `item_type: "file"` mode is step 2 of the Library upload flow; step 1 is [Create Upload](/features/memorylake/api-reference/library/create-upload) (same permission). If you then need the file to appear inside a project, call [Import Documents](/features/memorylake/api-reference/v3-documents/import-documents) — that additionally requires [`project:doc_add`](/features/team-collaboration/permission-reference#add-a-document-to-a-project).
</Note>

### Request Body

<Tabs>
  <Tab title="Create folder">
    <ParamField body="item_type" type="string" required>
      Must be `"folder"`.
    </ParamField>

    <ParamField body="parent_item_id" type="string" required>
      Parent folder — `MY_SPACE` or any folder's `item_id`.
    </ParamField>

    <ParamField body="name" type="string" required>
      Folder name, e.g. `Q2 Reports`.
    </ParamField>

    <ParamField body="name_conflict_strategy" type="string" default="rename">
      Behavior if the name already exists in `parent_item_id`:

      * `rename` *(default)* — append a numeric suffix (`Q2 Reports_1`).
      * `deny` — fail with `409 DRIVE_ITEM_CONFLICT`.
    </ParamField>

    <ParamField body="x_attrs" type="object">
      Extended attributes — a `string → string` map for caller-defined metadata.
    </ParamField>
  </Tab>

  <Tab title="Create file">
    This call finalizes an upload you opened earlier — it does not transfer bytes. Before you reach here you should have:

    1. Called [Create Upload](/features/memorylake/api-reference/library/create-upload) with `file_size` and received an `upload_id` + one pre-signed URL per chunk.
    2. PUT every chunk to its URL and saved the `ETag` header of each response.

    <ParamField body="item_type" type="string" required>
      Must be `"file"`.
    </ParamField>

    <ParamField body="parent_item_id" type="string" required>
      Parent folder — `MY_SPACE` or any folder's `item_id`.
    </ParamField>

    <ParamField body="name" type="string" required>
      File name, e.g. `report.pdf`.
    </ParamField>

    <ParamField body="from" type="object" required>
      Reference to the completed chunked upload.

      <Expandable title="from">
        <ParamField body="upload_id" type="string" required>
          The `upload_id` returned by [Create Upload](/features/memorylake/api-reference/library/create-upload).
        </ParamField>

        <ParamField body="part_etags" type="array" required>
          One entry per uploaded chunk. Include every chunk, in order.

          <Expandable title="part_etags item">
            <ParamField body="number" type="integer" required>
              Chunk number (1-based). Must match the `number` from the upload session.
            </ParamField>

            <ParamField body="etag" type="string" required>
              `ETag` header value returned when you PUT that chunk.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="name_conflict_strategy" type="string" default="rename">
      Behavior if the name already exists in `parent_item_id`:

      * `rename` *(default)* — append a numeric suffix (`report_1.pdf`).
      * `deny` — fail with `409 DRIVE_ITEM_CONFLICT`.
      * `overwrite` — overwrite the existing file's content in the Library. The existing `item_id` is **preserved**.
      * `replace` — delete the existing file and create a new one. A **new `item_id`** is issued; prior references to the old ID become stale.
    </ParamField>

    <Warning>
      `overwrite` only replaces the file bytes stored in the Library — it does **not** re-process or re-index any project documents that were previously imported from the file. To propagate new content into a project, call [Import Documents](/features/memorylake/api-reference/v3-documents/import-documents) again after the overwrite (or use a fresh file).
    </Warning>

    <ParamField body="x_attrs" type="object">
      Extended attributes — a `string → string` map for caller-defined metadata.
    </ParamField>
  </Tab>
</Tabs>

<RequestExample>
  ```bash Create folder theme={null}
  curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v1/drives/items' \
    -H 'Authorization: Bearer sk_xxxxxx' \
    -H 'Content-Type: application/json' \
    -d '{
      "item_type": "folder",
      "parent_item_id": "MY_SPACE",
      "name": "Q2 Reports"
    }'
  ```

  ```bash Create file theme={null}
  curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v1/drives/items' \
    -H 'Authorization: Bearer sk_xxxxxx' \
    -H 'Content-Type: application/json' \
    -d '{
      "item_type": "file",
      "parent_item_id": "MY_SPACE",
      "name": "report.pdf",
      "from": {
        "upload_id": "upl-abc123def456",
        "part_etags": [
          { "number": 1, "etag": "d41d8cd98f00b204e9800998ecf8427e" },
          { "number": 2, "etag": "f6e5d4c3b2a10987f6e5d4c3b2a10987" }
        ]
      }
    }'
  ```
</RequestExample>

### Response

The response shape is the same for folders and files.

<ResponseField name="data" type="object">
  <Expandable title="Created item">
    <ResponseField name="uri" type="string">Drive resource URI of the created item</ResponseField>
    <ResponseField name="item_id" type="string">ID of the resulting item. With `overwrite`, this equals the existing file's `item_id` (preserved). With `replace`, `rename`, or a fresh creation, a new `item_id` is issued.</ResponseField>
    <ResponseField name="name" type="string">Effective name. Differs from the requested `name` when `rename` produced an auto-suffix.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true,
    "data": {
      "uri": "drive://items/sc-5c6bf0f82d624a20a6fa4696997bdd46:7d8cf1e93f634b31b5",
      "item_id": "sc-5c6bf0f82d624a20a6fa4696997bdd46:7d8cf1e93f634b31b5",
      "name": "report.pdf"
    }
  }
  ```
</ResponseExample>

<Tip>
  Always read `name` from the response. With the default `rename` strategy, the server may have appended a suffix — the returned `name` is what you should display and store.
</Tip>