CrucibleClient

The main entry point for the nano-crucible Python API. Instantiating CrucibleClient loads credentials from config or environment variables and initializes all resource namespaces.

from crucible import CrucibleClient

client = CrucibleClient()
# or with explicit credentials:
client = CrucibleClient(api_url="https://crucible.lbl.gov/api/v2", api_key="your-key")

Resource namespaces

Attribute	Type	Description
client.datasets	DatasetOperations	Dataset CRUD, file upload/download, thumbnails, metadata
client.samples	SampleOperations	Sample CRUD, hierarchies, dataset links
client.projects	ProjectOperations	Project CRUD, user management
client.instruments	InstrumentOperations	Instrument CRUD
client.users	UserOperations	User management (admin)
client.files	FileOperations	File lookup, download, and ingestion by MFID
client.account	AccountOperations	Self-service profile, API key, verification
client.ingestions	IngestionOperations	Ingestion request management
client.graphs	GraphOperations	Entity graph traversal
client.deletions	DeletionOperations	Deletion request management

Reference

crucible.client.CrucibleClient

__init__(api_url=None, api_key=None)

Initialize the Crucible API client.

Parameters:

Name	Type	Description	Default
api_url	Optional[str]	Base URL for the Crucible API (loads from config if not provided)	None
api_key	Optional[str]	API key for authentication (loads from config if not provided)	None

Raises:

Type	Description
ValueError	If api_url or api_key not provided and not found in config

health()

Check API and database health without requiring authentication.

Returns:

Name	Type	Description
Dict	Dict	{"status": "ok"|"degraded", "db": "ok"|"error", "db_ms": float|None, "version": str|None} Raises requests.exceptions.ConnectionError if the host is unreachable.

live()

Check whether the API process is running (no DB check, no auth).

Returns:

Name	Type	Description
Dict	Dict	{"status": "ok"}

whoami()

Return full auth context for the current API key.

Delegates to client.account.whoami(). Kept here for backward compatibility and because it spans the account context rather than a specific resource.

get(resource_id, resource_type=None, include_metadata=False, include_links=False, include_owner=False)

Get a resource by ID with automatic type detection.

Parameters:

Name	Type	Description	Default
resource_id	str	The unique identifier (mfid) of the resource	required
resource_type	str	Resource type ('sample', 'dataset', 'instrument'). If not provided, will be auto-detected.	None
include_metadata	bool	Include scientific metadata	False
include_links	bool	Include immediate parent/child/associated links	False
include_owner	bool	Resolve owner_orcid into a full user object	False

Returns:

Name	Type	Description
Dict	Dict	Resource data

Raises:

Type	Description
ValueError	If resource type is unknown or not supported

get_resource_type(resource_id)

Determine the type of a resource.

Parameters:

Name	Type	Description	Default
resource_id	str	The unique identifier (mfid) of the resource	required

Returns:

Name	Type	Description
str	str	resource_type

get_links(resource_id)

Return immediate links for any resource (dataset or sample).

Hits GET /resources/{id}/links and returns a flat list of link dicts: [{"unique_id": "...", "resource_type": "dataset|sample", "name": "...", "relationship": "parent|child|associated"}, ...]

Parameters:

Name	Type	Description	Default
resource_id	str	Dataset or sample unique identifier	required

Returns:

Name	Type	Description
list	list	Link objects, or empty list if none

link(parent_id, child_id)

Link two resources with automatic type detection.

Automatically determines resource types and creates appropriate link: - Both datasets: Creates parent-child dataset relationship - Both samples: Creates parent-child sample relationship - Dataset + sample: Links sample to dataset

Parameters:

Name	Type	Description	Default
parent_id	str	Parent resource unique identifier	required
child_id	str	Child resource unique identifier	required

Returns:

Name	Type	Description
Dict	Dict	Information about the created link

Raises:

Type	Description
ValueError	If resource types cannot be determined or combination is invalid

Example

Link two datasets

client.link('parent_dataset_id', 'child_dataset_id')

Link two samples

client.link('parent_sample_id', 'child_sample_id')

Link sample to dataset

client.link('dataset_id', 'sample_id')

unlink(id_a, id_b)

Unlink two resources with automatic type detection.

Automatically determines resource types and removes the appropriate link: - Both datasets: Removes parent-child dataset relationship - Both samples: Removes parent-child sample relationship - Dataset + sample: Removes dataset-sample link

Parameters:

Name	Type	Description	Default
id_a	str	First resource unique identifier (dataset or sample)	required
id_b	str	Second resource unique identifier (dataset or sample)	required

Returns:

Name	Type	Description
Dict	Dict	Deletion confirmation

Raises:

Type	Description
ValueError	If resource types cannot be determined or combination is invalid.