labapi

A Python client for the LabArchives API.

labapi authenticates with LabArchives, navigates notebook trees, and creates or updates notebook content from Python.

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.

License

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