Skip to main content

aiobsidian

CI PyPI Python License Docs

Async Python client for the Obsidian Local REST API plugin.


Installation

pip install aiobsidian

Or with uv:

uv add aiobsidian

Quick start

import asyncio
from aiobsidian import ObsidianClient

async def main():
    async with ObsidianClient("your-api-key") as client:
        # Server status
        status = await client.system.status()
        print(status.versions.obsidian)

        # Read a note
        content = await client.vault.get("notes/hello.md")
        print(content)

        # Create a note
        await client.vault.update("notes/new.md", "# New Note\n\nContent here.")

        # Search
        results = await client.search.simple("hello")
        for r in results:
            print(r.filename, r.score)

        # Execute a command
        await client.commands.execute("daily-notes")

asyncio.run(main())

Features

  • Full async/await support via httpx

  • Complete API coverage — all Obsidian Local REST API endpoints:

    Resource Description
    Vault CRUD operations on any file
    Active Operations on the currently open file
    Periodic Daily, weekly, monthly, quarterly, yearly notes
    Commands List and execute Obsidian commands
    Search Simple text search, Dataview DQL, JsonLogic
    Open Open files in Obsidian UI
    System Server status, OpenAPI spec
  • Pydantic v2 models for type-safe responses

  • Custom exception hierarchy with error codes

  • Bring-your-own httpx.AsyncClient support

  • Context manager lifecycle management

Configuration

client = ObsidianClient(
    "your-api-key",
    host="127.0.0.1",      # default
    port=27124,             # default (HTTPS)
    scheme="https",         # default
    timeout=30.0,           # default
    verify_ssl=False,       # default (self-signed cert)
)

External HTTP client

You can provide your own httpx.AsyncClient for full control over transport settings:

import httpx
from aiobsidian import ObsidianClient

async with httpx.AsyncClient(timeout=60.0, verify=False) as http:
    async with ObsidianClient("your-api-key", http_client=http) as client:
        status = await client.system.status()

When an external client is provided, aiobsidian will not close it — you manage its lifecycle.

Documentation

Full documentation is available at kudato.github.io/aiobsidian.

Contributing

Contributions are welcome! Please see the Contributing Guide for details.

License

MIT

Metadata

Release files for aiobsidian 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiobsidian 0.1.1
File Size Uploaded Provenance Actions
aiobsidian-0.1.1.tar.gz 28.4 kB With provenance Details for aiobsidian-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiobsidian 0.1.1
File Interpreter ABI Platform Actions
aiobsidian-0.1.1-py3-none-any.whl Python 3 none any Details for aiobsidian-0.1.1-py3-none-any.whl

Total release size: 46.4 kB

Release files / aiobsidian-0.1.1.tar.gz

Download URL aiobsidian-0.1.1.tar.gz
Size 28.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f920394f01bc2c74c02ccbad9c174412dc6ab5644467a6f624f3000783fcb125
BLAKE2b-256 checksum
How to use checksums
993af463087793201e463deda8792ccd482bb2d4cccf984ca5094820125fca08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 15, 2026.

Transparency log

Release files / aiobsidian-0.1.1-py3-none-any.whl

Download URL aiobsidian-0.1.1-py3-none-any.whl
Size 18.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
02546a11d9137005d0132fb1536df8e6c6dc6f660e21b15508ba532486b0d268
BLAKE2b-256 checksum
How to use checksums
f918a70a5497c3e200f1597ee8ef25be2cba69d3ecef76b8f61dee988d46a561
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 15, 2026.

Transparency log

Security for aiobsidian 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiobsidian-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page