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

# Files and folders

> Understand stable IDs, paths, parent folders, supported content, and file protection.

Files hold Markdown or plain-text content. Folders organize those files within a workspace's context repository.

## IDs and paths

| Field          | Meaning                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`           | Stable identifier: `doc_…` for a file or `dir_…` for a folder. Use it for later reads and updates.                 |
| `path`         | Absolute location, such as `/support/refunds.md`. Changes when an item or a containing folder moves or is renamed. |
| `parentId`     | ID of the containing folder, or `null` at the root.                                                                |
| `parentPath`   | Path of the containing folder, or `/` at the root.                                                                 |
| `lastChangeId` | A file's last content change. Use it as `baseChangeId` when replacing content.                                     |

Renaming or moving a file does not change its ID or advance its `lastChangeId`. Moving a folder preserves the IDs of the items below it.

## Create by path or parent

Create a file with either `path` and `content`, or `parentId`, `name`, and `content`. Create a folder with either `path`, or `parentId` and `name`. Use one alternative per request.

A path creates missing parent folders automatically. Set `parentId` to `null` to create at the root. An existing path returns `409 path_already_exists`; creation does not update an existing item.

File paths are absolute and end in lowercase `.md`. Folder paths do not end in `.md`. See [Errors and limits](/api-docs/errors#limits) for content and naming limits.

## Read and find content

[Get a file](/api-docs/files/get-file) returns metadata and its full content. [List files](/api-docs/files/list-files) returns metadata; use `path` when you know the exact location but not the ID.

Use [hybrid search](/api-docs/search/hybrid-search) to find relevant files by meaning, or [regex search](/api-docs/search/regex-search) to find matching lines. Search only returns content the key can read. Newly written content may take a moment to appear in search; direct reads and lists do not have that indexing delay.

Keys restricted to part of the repository may receive incomplete search results, including an empty response when readable matches exist. See [Search results with restricted access](/api-docs/search/hybrid-search#results-with-restricted-access).

## Protection and deletion

Protection routes content changes through review. Read [Updating content](/api-docs/updating-content) before implementing writes.

Deleting a file removes its change history and cannot be reversed through the API. Folder deletion requires `recursive=true` when the folder has contents. Confirm the intended scope before using recursive deletion; see the endpoint's error responses for conditions that prevent deletion.