Skip to content

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

A new client uses the first credential it finds: an api_key argument, then CRUCIBLE_API_KEY, then the sign-in stored by crucible login or client.login(), then api_key in the config file. client.credential_source reports which one is in use. client.login() signs in with a browser (method="device" approves a code on any device, for SSH or headless machines; method="paste" asks for the code the sign-in page shows, for when the browser cannot reach the program) and switches the client to that session; client.logout() ends and forgets the stored sign-in.

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 keys, verification
client.ingestions IngestionOperations Ingestion request management
client.postprocessing PostprocessingOperations Postprocessing pipelines and runs
client.graphs GraphOperations Entity graph traversal
client.deletions DeletionOperations Deletion request management
client.access_groups AccessGroupOperations Project join requests
client.service_accounts ServiceAccountOperations Service-account creation, key rotation, and administration
client.print PrintOperations Label-printer jobs

Privilege mode

Endpoints distinguish normal ACL-derived authorization from explicit platform-administrator elevation, selected with the Crucible-Privilege-Mode header. By default the client sends no header and the server decides: a platform administrator using an API key runs elevated and sees every record, a signed-in administrator runs normal, and everyone else gets their normal, ACL-derived access. client.is_elevated reports the mode the server applies.

Pass privilege_mode="normal" to see only what you can access through your own memberships and grants, or "elevated" to request elevation explicitly. The privilege_mode config key and CRUCIBLE_PRIVILEGE_MODE environment variable set the same thing.

client = CrucibleClient(privilege_mode="normal")

A future release will default to normal for API keys too. Platform administrators whose scripts rely on seeing every record should set privilege_mode = elevated now.

Administrator-only operations, such as service-account administration and deletion review, request elevation per call, so they work without elevating the whole client. Requesting elevation as an ineligible caller is rejected with a 403, so those calls elevate only when client.can_elevate is true.

Authorization and capabilities

client.authorization (an AccountAuthorization) and client.capabilities (an AccountCapabilities) expose the caller's platform role and account-level permissions. They are read once from /account/profile and cached; call client.refresh_profile() to re-read them, for example after changing privilege_mode or after an administrator changes your role.

if client.capabilities.can_create_project:
    client.projects.create(...)

A flag the profile did not report is None, so check for an explicit False before refusing; otherwise attempt the operation and let the API decide.

Reference

crucible.client.CrucibleClient

credential_source property

What this client authenticates with: 'argument', 'CRUCIBLE_API_KEY', 'config file' (API keys), 'sign-in' (stored by login), or 'this session'.

authorization property

The caller's platform_role and whether they can elevate.

Fetched once from /account/profile and cached; call refresh_profile() to re-read it. An unreadable profile yields empty values, so callers degrade to "no extra authority" rather than failing.

capabilities property

The caller's account-level capability flags, cached like authorization.

They describe the authority of the privilege mode the client was in when the profile was read; call refresh_profile() after changing privilege_mode.

can_elevate property

Whether this caller may request elevated privilege mode at all.

is_elevated property

Whether ordinary requests from this client run elevated.

Without an explicit mode the server decides: it elevates an administrator's API key but not a sign-in, and reports which.

__init__(api_url=None, api_key=None, privilege_mode=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
privilege_mode Optional[str]

"normal" or "elevated". Sent as the Crucible-Privilege-Mode header on every request. Elevated mode is what lets a platform administrator see beyond their own ACL-derived access. Loads from config if not provided. When unset, no header is sent and the server applies its legacy behavior: elevated for a platform administrator, normal for everyone else. Admin-only operations request elevation per call regardless of this setting.

None

Without api_key, the client uses CRUCIBLE_API_KEY, then the sign-in stored by crucible login for api_url, then api_key from the config file.

Raises:

Type Description
NotSignedInError

If there is no API key and no stored sign-in (a ValueError)

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

login(method='auto', store=None, open_browser=True, notify=print)

Sign in with a browser and use that session from now on.

Parameters:

Name Type Description Default
method str

'browser' (this computer's browser), 'paste' (any browser; you paste the code its page shows, for when the browser cannot reach this machine), 'device' (a code approved in any browser, for SSH or headless machines), or 'auto', which picks the browser when one is available here.

'auto'
store Optional[str]

Where to keep the tokens: 'auto' (the OS keyring, else a 0600 file), 'keyring', 'file', or 'memory' (this client only). Defaults to the auth_store setting.

None
open_browser bool

Open the browser automatically for the browser method.

True
notify Callable[[str, str], None]

Called with (message, url) to show the person where to go.

print

Returns:

Name Type Description
Dict Dict

{'user_unique_id', 'store', 'grant'}

logout()

End and forget the sign-in stored for this API address.

Returns:

Name Type Description
bool bool

False when there was no stored sign-in.

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.

refresh_profile()

Re-read authorization and capabilities from /account/profile.

get(resource_mfid, resource_type=None, include_metadata=False, include_links=False, include_owner=True, include_datasets=False)

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 the owner into a public-safe user object (default: True)

True
include_datasets bool

For samples, also embed the linked dataset records (default: False). Deprecated by the API: use include_links.

False

Returns:

Name Type Description
Dict Optional[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

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

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

client.link(parent_mfid, child_mfid)

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

client.link(dataset_mfid, sample_mfid)

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.