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 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 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 find relevant files by meaning, or 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.

​
Protection and deletion

Protection routes content changes through review. Read 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.