Build, Connect, and Automate with the ELabELN API

Experiments are the primary research record in ELabELN. The API supports the full lifecycle of an experiment: creating new entries from scratch or from a template, reading existing experiments individually or in filtered lists, modifying the body content and metadata, duplicating entries for repeating workflows, and archiving entries that are no longer active. Experiments carry their status, category, ownership, and team scope through the API the same way they do in the application.

Resources are the structured records the lab uses to track samples, reagents, instruments, materials, equipment, and any other item that needs a persistent identifier in the system. The API exposes the same lifecycle operations as experiments. Resources can be created from a resource template, retrieved individually or as a filtered list, modified, duplicated for routine sample types, and archived when retired. Resources can be linked to experiments and to compounds to capture the relationships between physical items and the work that uses them.

Templates standardize record creation for workflows that repeat. The API manages templates for both experiments and for resource types, including duplication of existing templates as a starting point for new ones. Programmatic template management is useful for organizations that want to maintain a central library of approved protocols, SOPs, and resource definitions and propagate updates across teams.

The compound library holds structured chemical records that can be referenced from experiments and resources. The API supports creating compound records directly, importing them in bulk, retrieving individual records, and soft-deleting compounds that are no longer needed. Compound records can be linked to experiments and to resources so that the chemical context of any work is traceable from the record outward.

The API exposes the full relationship surface used by the application. Experiments can be linked to other experiments to capture follow-on work, to resources for the samples and reagents used, and to compounds for the chemicals involved. The same applies to resource records, which can link to other resources, to experiments, and to compounds. Reading the links on a record reveals the full graph of related work without needing to query each record individually.

Files attached to a record (instrument output, images, supporting documents) are managed through the API the same way they are through the application. Files can be uploaded, retrieved, replaced, modified, and removed. When a file is replaced, the prior version is preserved as an archived attachment rather than overwritten, so the full history of every file on every record remains queryable.

Comments capture commentary, review notes, and inter-researcher discussion against a specific record. The API supports the full comment lifecycle: reading all comments on a record, creating new comments, modifying existing ones, and removing them. Comments are useful for review-and-signoff workflows and for capturing the reasoning around a record that does not belong in the record body itself.

Steps break a record into procedural items that can be checked off as the work proceeds. The API supports reading the steps on a record, creating new steps, marking them complete, modifying them, and removing them. An instance-wide view of unfinished steps across all accessible records is also available, useful for surfacing in-progress work in dashboards and reports.

Tags provide a flexible taxonomy that crosses the experiment-and-resource boundary. The API supports team-level tag management (creating, reading, modifying, and removing tags from the team's tag library) and per-record tag operations. Users can also mark tags as favorites for quick retrieval. Tags are useful for cross-cutting attributes (project, instrument, study) that do not fit neatly into a single category.

Every record carries a revision history of its prior states. The API exposes this history for read access and supports restoring a record to a prior revision when an unintended change needs to be reversed. Revision access is foundational to the audit and change-tracking story for regulated and accredited environments and is available across the entity types managed by the system.

Records in ELabELN can carry extra fields beyond the built-in attributes, defined as part of the record body or via templates. The API exposes the set of extra-field keys in use across the instance. This is useful for integration scenarios where downstream systems need to discover the custom schema in play without having to inspect every record.

The API supports user lifecycle management for administrators. New users can be provisioned programmatically, user records can be read individually or in lists, and user attributes can be modified. This is useful for environments that provision lab informatics access alongside other systems through a central identity management process. Per-user attached file lists are also accessible.

Teams are the primary scoping mechanism for records, tags, categories, and statuses. The API supports reading the team list (requires sysadmin scope), creating new teams, and modifying team attributes. Team groups inside a team can also be managed programmatically, which is useful for sub-team organization in larger deployments.

Categories and statuses are team-scoped definitions that classify experiments and resources. Categories provide a taxonomy (project, study, equipment type), and statuses capture lifecycle position (in progress, complete, retired). The API supports independent management of all four sets: experiment categories, experiment statuses, resource categories, and resource statuses.

For federated identity scenarios, the API supports SAML identity provider configuration. IdPs can be registered, their endpoint definitions can be managed, and certificates can be added and removed. IdP sources, which describe upstream metadata services, can also be configured. This is the integration surface for connecting ELabELN to institutional or corporate single sign-on infrastructure.

API keys grant programmatic access and are themselves managed through the API. Keys can be listed, created with specific scope, and removed when no longer needed. Access granted by an API key is governed by the same role and team scoping that controls the corresponding user account in the web interface, so programmatic access does not bypass the permission model.

Instance-level configuration is readable and modifiable through the API for administrators. Usage reports are available for the team and the instance, supporting downstream reporting and analytics workflows. A general information endpoint returns instance metadata useful for integration smoke checks and version reporting.

Notifications surface system events to users (mentions in comments, attached file activity, booking events, and other triggers). The API supports reading notifications for a user, acknowledging individual notifications, and clearing the full notification queue. This is the integration surface for forwarding events to other systems or to user-facing dashboards.

Shared instruments and equipment are scheduled through the event and booking surface. The API supports reading the event list at the team level, creating booking slots against a specific resource (typically a shared instrument), modifying existing bookings, and cancelling them. This is the integration surface for connecting ELabELN's scheduling to external calendaring or facility-management systems.

Physical storage is modeled as a hierarchy of storage units (freezers, shelves, racks, boxes) with containers placed against specific records. The API supports managing the storage unit hierarchy itself and managing the containers attached to a record. The hierarchy can be retrieved as a flat list or as a tree structure. This is useful for sample-location reporting and for downstream inventory analytics.

The to-do list is a per-user task surface separate from procedural steps on records. The API supports reading the user's to-do list, creating new items, updating existing ones, and removing them. It complements the steps surface for tracking work that is not yet attached to a specific record.

Bulk data movement is handled through the import and export surface. The API supports submitting files for import and managing export requests across their lifecycle: registering an export request, retrieving the resulting file when ready, listing pending requests, and removing requests that are no longer needed. This is the integration surface for full-instance and per-team data movement.

For institutions that maintain a DSpace repository for long-term archival, the API supports creating a workspace item in DSpace and submitting an ELabELN entry to the repository. This connects the day-to-day work captured in ELabELN to the institutional record retention infrastructure that grant compliance and reproducibility programs often require.