Skip to main content
Files hold Markdown or plain-text content. Folders organize those files within a workspace’s context repository.

​
IDs and paths

Renaming or moving a file preserves its id but advances 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 for content and naming limits.

​
Read and find content

Get a file returns metadata and its full content. List files returns metadata; use path when you know the exact location but not the ID. Use hybrid search to combine word and meaning matches, or regex search to match a text pattern. Set mode to "passages" for matching excerpts or "files" for distinct files with full content. The limit counts passages or files according to the selected mode. Results include kind, text and the matched file in file, identified by file.id. When includeSources is true, sources lists the external records connected to that file. Regex requests require mode. Hybrid requests without mode still use the legacy full-file response format. When adding mode, use file.id in place of file.fileId and remove any dependency on file.url; each result also includes kind. 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.

​
Protection and deletion

Protection routes content changes through review. Read Updating content before implementing writes. Deleting a file removes it from the live context repository and cannot be reversed through the API. A protected file, or one inside a protected folder, refuses the delete. Changes in review do not block it; they are resolved against the delete when accepted. Folder deletion requires recursive=true when the folder has contents, and refuses when the folder, a folder inside it, or a file inside it is protected. A recursive request can delete at most 500 files and folders combined, including the selected folder. Larger trees return 422 too_many_edits; delete smaller subfolders or individual files first, then remove the empty parent folder. Confirm the intended scope before using recursive deletion; see the endpoint’s error responses for conditions that prevent deletion.