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_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 or the package default 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_key is not provided and not found in config

health()

Check API and database health without requiring authentication.

Returns:

Name	Type	Description
Dict	Dict	Readiness status with nested build and database provenance. During API rollout, older servers may return the legacy flat db, db_ms, and version fields.

Raises:

Type	Description
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_mfid, resource_type=None, include_metadata=False, include_links=False, include_owner=True, include_datasets=True)

Get a resource by ID with automatic type detection.

Parameters:

Name	Type	Description	Default
resource_mfid	str	Resource MFID	required
resource_type	str	Resource type ('sample', 'dataset', 'project', or '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 public-safe user object (default: True)	True
include_datasets	bool	For samples, include deprecated embedded dataset records (default: True)	True

Returns:

Name	Type	Description
Dict	Dict	Resource data

Raises:

Type	Description
ValueError	If resource type is unknown or not supported

get_resource_type(resource_mfid)

Determine the type of a resource.

Parameters:

Name	Type	Description	Default
resource_mfid	str	Resource MFID	required

Returns:

Name	Type	Description
str	str	resource_type

get_links(resource_mfid)

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": "...", "direction": "source|target|undirected", "relationship": "parent|child|associated", "relationship_type": "is_derived_from|is_part_of|null"}, ...]

direction says which end of the stored parent -> child edge this resource is, relative to the one you asked about: "source" means it is the parent, "target" the child. Dataset/sample associations have no hierarchy and are always "undirected". relationship_type is the kind of link, stored on the link row and oriented child-relative-to-parent; it is null on associations and on links created before typing existed. relationship remains as a compatibility alias for direction.

Parameters:

Name	Type	Description	Default
resource_mfid	str	Dataset or sample MFID	required

Returns:

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

link(parent_mfid, child_mfid, relationship_type=None)

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_mfid	str	Parent resource MFID	required
child_mfid	str	Child resource MFID	required
relationship_type	str	Kind of link, one of crucible.constants.RELATIONSHIP_TYPES. Only meaningful for dataset-to-dataset and sample-to-sample links; a dataset/sample association has no hierarchy to describe.	None

Returns:

Name	Type	Description
Dict	Dict	Information about the created link

Raises:

Type	Description
ValueError	If resource types cannot be determined, the combination is invalid, or relationship_type is given for a dataset/sample association

Example

Link two datasets

client.link(parent_mfid, child_mfid)

Link two samples, recording what kind of link it is

client.link(parent_mfid, child_mfid, relationship_type='is_part_of')

Link sample to dataset

client.link(dataset_mfid, sample_mfid)

unlink(resource_mfid_a, resource_mfid_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
resource_mfid_a	str	First dataset or sample MFID	required
resource_mfid_b	str	Second dataset or sample MFID	required

Returns:

Name	Type	Description
Dict	Dict	Deletion confirmation

Raises:

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