ObsidianClient (REST)

ObsidianClient(api_key, *, host=DEFAULT_HOST, port=DEFAULT_PORT, scheme=DEFAULT_SCHEME, timeout=DEFAULT_TIMEOUT, verify_ssl=False, http_client=None)

Async client for the Obsidian Local REST API.

Provides access to vault files, the active file, periodic notes, commands, search, and system information through resource properties.

Can be used as an async context manager:

async with ObsidianClient(api_key="your-key") as client:
    status = await client.system.status()

Parameters:

Name	Type	Description	Default
api_key	str	API key from the Local REST API plugin settings.	required
host	str	Hostname of the Obsidian REST API server.	DEFAULT_HOST
port	int	Port number of the Obsidian REST API server.	DEFAULT_PORT
scheme	str	URL scheme ("https" or "http").	DEFAULT_SCHEME
timeout	float	Request timeout in seconds.	DEFAULT_TIMEOUT
verify_ssl	bool	Whether to verify SSL certificates. Defaults to False because the plugin uses self-signed certificates.	False
http_client	AsyncClient | None	Optional pre-configured httpx.AsyncClient. When provided, the client will not be closed on aclose().	None

Source code in src/aiobsidian/_client.py

def __init__(
    self,
    api_key: str,
    *,
    host: str = DEFAULT_HOST,
    port: int = DEFAULT_PORT,
    scheme: str = DEFAULT_SCHEME,
    timeout: float = DEFAULT_TIMEOUT,
    verify_ssl: bool = False,
    http_client: httpx.AsyncClient | None = None,
) -> None:
    self._host = host
    self._port = port
    self._scheme = scheme
    self._base_url = f"{scheme}://{host}:{port}"
    self._api_key = api_key
    self._timeout = timeout
    self._verify_ssl = verify_ssl
    self._external_client = http_client is not None
    self._http = http_client or self._build_http_client()

vault cached property

Access vault file operations (read, create, append, patch, delete, list).

active cached property

Access the currently active file in Obsidian.

periodic cached property

Access periodic notes (daily, weekly, monthly, quarterly, yearly).

commands cached property

List and execute Obsidian commands.

search cached property

Search vault content (simple text, Dataview DQL, JsonLogic).

open cached property

Open files in the Obsidian UI.

system cached property

Access server status and OpenAPI specification.

request(method, path, *, content=None, json=None, headers=None, params=None) async

Send an HTTP request to the Obsidian REST API.

This is a low-level method used internally by resource classes. Prefer using the resource methods (e.g. client.vault.get()) for typical operations.

Parameters:

Name	Type	Description	Default
method	str	HTTP method (GET, POST, PUT, PATCH, DELETE).	required
path	str	API endpoint path (e.g. "/vault/note.md").	required
content	str | bytes | None	Raw request body.	None
json	Any	JSON-serializable request body.	None
headers	dict[str, Any] | None	Additional HTTP headers.	None
params	dict[str, Any] | None	URL query parameters.	None

Returns:

Type	Description
Response	The httpx.Response object.

Raises:

Type	Description
AuthenticationError	If the API key is invalid (HTTP 401).
NotFoundError	If the resource is not found (HTTP 404).
APIError	For any other HTTP error (status >= 400).

Source code in src/aiobsidian/_client.py

async def request(
    self,
    method: str,
    path: str,
    *,
    content: str | bytes | None = None,
    json: Any = None,
    headers: dict[str, Any] | None = None,
    params: dict[str, Any] | None = None,
) -> httpx.Response:
    """Send an HTTP request to the Obsidian REST API.

    This is a low-level method used internally by resource classes.
    Prefer using the resource methods (e.g. `client.vault.get()`)
    for typical operations.

    Args:
        method: HTTP method (GET, POST, PUT, PATCH, DELETE).
        path: API endpoint path (e.g. `"/vault/note.md"`).
        content: Raw request body.
        json: JSON-serializable request body.
        headers: Additional HTTP headers.
        params: URL query parameters.

    Returns:
        The `httpx.Response` object.

    Raises:
        AuthenticationError: If the API key is invalid (HTTP 401).
        NotFoundError: If the resource is not found (HTTP 404).
        APIError: For any other HTTP error (status >= 400).
    """
    response = await self._http.request(
        method,
        path,
        content=content,
        json=json,
        headers=headers,
        params=params,
    )
    if response.status_code >= 400:
        self._raise_for_status(response)
    return response

aclose() async

Close the underlying HTTP client.

If an external httpx.AsyncClient was provided to the constructor, this method is a no-op — the caller is responsible for closing it.

Source code in src/aiobsidian/_client.py

async def aclose(self) -> None:
    """Close the underlying HTTP client.

    If an external `httpx.AsyncClient` was provided to the
    constructor, this method is a no-op — the caller is
    responsible for closing it.
    """
    if not self._external_client:
        await self._http.aclose()