Vault Resource

VaultResource(client)

Bases: ContentResource

Operations on files and directories in the vault.

Source code in src/aiobsidian/rest/_base.py

def __init__(self, client: ObsidianClient) -> None:
    self._client = client

get(path, *, content_type=ContentType.MARKDOWN) async

get(
    path: str,
    *,
    content_type: Literal[ContentType.MARKDOWN] = ...,
) -> str

get(
    path: str,
    *,
    content_type: Literal[ContentType.NOTE_JSON],
) -> NoteJson

get(
    path: str,
    *,
    content_type: Literal[ContentType.DOCUMENT_MAP],
) -> DocumentMap

Get the content of a vault file.

Parameters:

Name	Type	Description	Default
path	str	Path to the file relative to the vault root (e.g. "Notes/hello.md").	required
content_type	ContentType	Desired response format. Use ContentType.MARKDOWN for raw text, ContentType.NOTE_JSON for structured JSON, or ContentType.DOCUMENT_MAP for headings/blocks.	MARKDOWN

Returns:

Type	Description
str | NoteJson | DocumentMap	File content as str, NoteJson, or DocumentMap
str | NoteJson | DocumentMap	depending on the requested content type.

Raises:

Type	Description
NotFoundError	If the file does not exist.

Source code in src/aiobsidian/rest/vault.py

async def get(
    self,
    path: str,
    *,
    content_type: ContentType = ContentType.MARKDOWN,
) -> str | NoteJson | DocumentMap:
    """Get the content of a vault file.

    Args:
        path: Path to the file relative to the vault root
            (e.g. `"Notes/hello.md"`).
        content_type: Desired response format. Use
            `ContentType.MARKDOWN` for raw text,
            `ContentType.NOTE_JSON` for structured JSON, or
            `ContentType.DOCUMENT_MAP` for headings/blocks.

    Returns:
        File content as `str`, `NoteJson`, or `DocumentMap`
        depending on the requested content type.

    Raises:
        NotFoundError: If the file does not exist.
    """
    return await self._get_content(f"{self._BASE_URL}/{path}", content_type)

update(path, content) async

Create or replace a file in the vault.

Parameters:

Name	Type	Description	Default
path	str	Path for the file relative to the vault root.	required
content	str	Markdown content to write.	required

Source code in src/aiobsidian/rest/vault.py

async def update(self, path: str, content: str) -> None:
    """Create or replace a file in the vault.

    Args:
        path: Path for the file relative to the vault root.
        content: Markdown content to write.
    """
    await self._client.request(
        "PUT",
        f"{self._BASE_URL}/{path}",
        content=content,
        headers={"Content-Type": ContentType.MARKDOWN},
    )

append(path, content) async

Append content to the end of a vault file.

Parameters:

Name	Type	Description	Default
path	str	Path to the file relative to the vault root.	required
content	str	Markdown content to append.	required

Raises:

Type	Description
NotFoundError	If the file does not exist.

Source code in src/aiobsidian/rest/vault.py

async def append(self, path: str, content: str) -> None:
    """Append content to the end of a vault file.

    Args:
        path: Path to the file relative to the vault root.
        content: Markdown content to append.

    Raises:
        NotFoundError: If the file does not exist.
    """
    await self._append_content(f"{self._BASE_URL}/{path}", content)

patch(path, content, *, operation, target_type, target, target_delimiter='::') async

Patch a specific section of a vault file.

Parameters:

Name	Type	Description	Default
path	str	Path to the file relative to the vault root.	required
content	str	Content to insert or replace.	required
operation	PatchOperation	How to apply the content (append, prepend, or replace).	required
target_type	TargetType	What to target (heading, block, or frontmatter).	required
target	str	The target identifier (e.g. heading text, block ID, or frontmatter field name).	required
target_delimiter	str	Delimiter for nested targets.	'::'

Raises:

Type	Description
NotFoundError	If the file does not exist.

Source code in src/aiobsidian/rest/vault.py

async def patch(
    self,
    path: str,
    content: str,
    *,
    operation: PatchOperation,
    target_type: TargetType,
    target: str,
    target_delimiter: str = "::",
) -> None:
    """Patch a specific section of a vault file.

    Args:
        path: Path to the file relative to the vault root.
        content: Content to insert or replace.
        operation: How to apply the content (`append`, `prepend`,
            or `replace`).
        target_type: What to target (`heading`, `block`, or
            `frontmatter`).
        target: The target identifier (e.g. heading text, block ID,
            or frontmatter field name).
        target_delimiter: Delimiter for nested targets.

    Raises:
        NotFoundError: If the file does not exist.
    """
    await self._patch_content(
        f"{self._BASE_URL}/{path}",
        content,
        operation=operation,
        target_type=target_type,
        target=target,
        target_delimiter=target_delimiter,
    )

delete(path) async

Delete a file from the vault.

Parameters:

Name	Type	Description	Default
path	str	Path to the file relative to the vault root.	required

Raises:

Type	Description
NotFoundError	If the file does not exist.

Source code in src/aiobsidian/rest/vault.py

async def delete(self, path: str) -> None:
    """Delete a file from the vault.

    Args:
        path: Path to the file relative to the vault root.

    Raises:
        NotFoundError: If the file does not exist.
    """
    await self._client.request("DELETE", f"{self._BASE_URL}/{path}")

list(path='') async

List files in a vault directory.

Parameters:

Name	Type	Description	Default
path	str	Directory path relative to the vault root. Empty string for the root directory.	''

Returns:

Type	Description
VaultDirectory	A VaultDirectory containing the list of file paths.

Source code in src/aiobsidian/rest/vault.py

async def list(self, path: str = "") -> VaultDirectory:
    """List files in a vault directory.

    Args:
        path: Directory path relative to the vault root.
            Empty string for the root directory.

    Returns:
        A `VaultDirectory` containing the list of file paths.
    """
    path = path.strip("/")
    trailing = f"{path}/" if path else ""
    response = await self._client.request("GET", f"{self._BASE_URL}/{trailing}")
    return VaultDirectory.model_validate(response.json())