labapi

A high-level Python interface to LabArchives notebooks.

labapi allows you to work with the LabArchives API through familiar lab notebook concepts. It represents notebooks, folders, pages, and entries as Python objects. It provides easy, path-based navigation and unified access to LabArchives attachments, as well as convenience methods for common higher-level operations like searching notebook entries and getting or creating pages and folders by path.

The library handles authentication, request signing, XML response parsing, search-result pagination, and entry-type decoding.

Source | Docs | Issues

Start Here

• New to labapi? Follow the First Success Tutorial to install labapi, authenticate, and create your first LabArchives entry.
• Already using labapi? Jump to the Quick Start, User Guide, Examples, or FAQ.
• Working on the package itself? Start with CONTRIBUTING.md.

Install

Requirements:

• Python 3.10+
• 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.

Configure Credentials

LabArchives issues API keys on request. Ask your institution's LabArchives site administrator or Enterprise Success Team contact to request API access, or contact support@labarchives.com. LabArchives provides the Access Key ID, Access Password, and the API base URL for your region.

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].

Quick Start

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>")

Common Tasks

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")

Documentation Map

• First Success Tutorial: install, authenticate, and create a first entry.
• Quick Start: setup, navigation, page creation, uploads, and basic write operations.
• Authentication Guide: browser authentication, terminal/manual authentication, and callback URL authentication.
• User Guide: paths, entries, API behavior, exceptions, limits, and architecture notes.
• Examples: scripts for JSON sync, folder export, and CSV table updates.
• FAQ: authentication, certificate, and environment troubleshooting.

Development

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.

AI Usage Disclosure

The authors designed labapi's foundational architecture and implemented its core. Generative AI subsequently assisted with development, testing, maintenance, release work, and project documentation. The authors retain final control over the library's scope, behavior, and public interface and take responsibility for the software, reviewing and accepting AI-assisted changes through public pull requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.