A Python client for the LabArchives API.

labapi helps you authenticate with LabArchives, navigate notebook trees, and create or update notebook content from Python.

Source | Docs | Issues

• New to labapi? Follow the First Success Tutorial for the fastest path from install to a visible change in LabArchives.
• Already using labapi? Jump to the Quick Start, User Guide, Examples, or FAQ.
• Working on the package itself? Start with CONTRIBUTING.md.

Requirements:

• Python 3.12+
• uv (recommended) or pip

Recommended install for local use:

uv add "labapi[dotenv,builtin-auth]"
# or
pip install "labapi[dotenv,builtin-auth]"

Other install options:

# Minimal install
uv add labapi
# or
pip install labapi

# Minimal install plus .env loading
uv add "labapi[dotenv]"
# or
pip install "labapi[dotenv]"

Extras:

• dotenv loads API_URL, ACCESS_KEYID, and ACCESS_PWD from a local .env file.
• builtin-auth enables default_authenticate() to open the LabArchives login flow in a local browser.

Add your LabArchives API credentials to a .env file:

API_URL=https://api.labarchives.com
ACCESS_KEYID=your_access_key_id
ACCESS_PWD=your_access_password

Or set them directly in your shell:

export API_URL=https://api.labarchives.com
export ACCESS_KEYID=your_access_key_id
export ACCESS_PWD=your_access_password

$env:API_URL="https://api.labarchives.com"
$env:ACCESS_KEYID="your_access_key_id"
$env:ACCESS_PWD="your_access_password"

.env files are only auto-loaded when python-dotenv is installed, such as with labapi[dotenv].

from datetime import datetime

from labapi import Client, NotebookPage, TextEntry

with Client() as client:
    user = client.default_authenticate()

    notebook_name = next(iter(user.notebooks))
    notebook = user.notebooks[notebook_name]
    page = notebook.create(
        NotebookPage,
        f"API tutorial - {datetime.now():%Y-%m-%d %H:%M:%S}",
    )
    page.entries.create(TextEntry, "<p>Hello from labapi!</p>")

This is the recommended local workflow:

1. Install labapi[dotenv,builtin-auth].
2. Set API_URL, ACCESS_KEYID, and ACCESS_PWD.
3. Call default_authenticate() once the client is open.
4. Start creating or updating notebooks, folders, pages, and entries through the object model.

Authenticate in a service or callback-based app:

from labapi import Client

with Client() as client:
    auth_url = client.generate_auth_url(callback_url)
    # Redirect the user to auth_url, then read email + auth_code
    user = client.login(email, auth_code)

Create different entry types:

from labapi import HeaderEntry, PlainTextEntry, TextEntry

page.entries.create(TextEntry, "<p>Rich text content</p>")
page.entries.create(HeaderEntry, "Final Conclusions")
page.entries.create(PlainTextEntry, "<p>Literal text</p>")
page.entries.create_json_entry({"yield": 0.85, "purity": "99%"})

Browse notebooks by name and path:

for name in user.notebooks:
    print(name)

notebook = user.notebooks["My Research Notebook"]
page = notebook.traverse("Experiments/2026/Results")

• First Success Tutorial: shortest path from install to a successful write.
• Quick Start: setup, navigation, page creation, uploads, and basic write operations.
• Authentication Guide: local browser auth, manual flows, and callback-based integration patterns.
• User Guide: paths, entries, API behavior, exceptions, limits, and architecture notes.
• Examples: end-to-end scripts for real workflows.
• FAQ: troubleshooting and environment questions.

Clone the repo and install development dependencies:

git clone https://github.com/nimh-dsst/labapi.git
cd labapi
uv sync --all-groups
pre-commit install --hook-type pre-commit --hook-type pre-push

Common checks:

uv run pytest
uv run ruff check --fix .
uv run ruff format .
uv run pyright

Integration tests are opt-in and require live credentials. See CONTRIBUTING.md for the full setup, including AUTH_EMAIL and AUTH_KEY.

This project is licensed under the CC0 1.0 Universal License. See the LICENSE file for details.