Skip to content

InstrumentOperations

Access via client.instruments.

Store instruments by MFID (unique_id). The instrument slug (instrument_id) is for human lookup and ignores case; every method that takes an instrument reference accepts either. instrument_name is free-text display, may repeat, and must not be used to identify an instrument.

Instrument members work like project members (list_users(), add_user(), remove_user(), update_user_role(), each returning ProjectMember records): every member reads the instrument's datasets, editor also edits details, and admin also changes status, binds service accounts, and manages members. Service accounts are bound with bind_service_account() instead. set_access() and revoke_access() raise RemovedError for instruments; list_access(), set_public(), and set_private() still work.

crucible.resources.instruments.InstrumentOperations

Instrument-related API operations.

Access via: client.instruments.get(), client.instruments.list(), etc.

list(include_metadata=False, limit=DEFAULT_LIMIT, offset=0, include_owner=False, status=None, affiliation=None, sort=None, direction=None, cursor=None, mfid=None, **filters)

List instruments, defaulting to the active lifecycle state.

Parameters:

Name Type Description Default
include_metadata bool

Include scientific metadata in results

False
limit int

Maximum number of results to return

DEFAULT_LIMIT
offset int

Starting position in the full result set (default: 0)

0
cursor str

Continuation token from a previous result's next_cursor; the listing resumes there.

None
include_owner bool

Resolve the owner into a public-safe user object

False
status str

Filter by active, maintenance, or decommissioned. When omitted, the API defaults to active (or every status for an instrument_id lookup).

None
affiliation Optional[Union[str, Sequence[str]]]

Caller relationship: 'owner', 'maintainer' (editor or admin member), or 'member' (any role), combined with OR, to list the caller's instruments.

None
sort Optional[str]

Explicit ordering, one of crucible.constants.INSTRUMENT_SORTS.

None
direction Optional[str]

Sort direction, asc or desc. Requires sort. Without it, dates default to desc and everything else to asc.

None
mfid str or list

Only these instrument MFIDs (up to 100).

None
**filters Any

Exact-match filters accepted by GET /instruments, such as instrument_id (case-insensitive slug), manufacturer, model, location, instrument_type, owner_ref (up to 10 owners), other_id.

{}

Returns:

Type Description
List[Dict]

List[Dict]: Instrument objects with specifications, the caller's effective role on each record, and metadata

get(instrument_ref=None, instrument_id=None, include_metadata=False, include_owner=True, *, instrument_mfid=None, instrument_name=None, include_members=False)

Get an instrument by canonical MFID or human-readable slug.

instrument_id explicitly selects the human-readable API identifier.

Parameters:

Name Type Description Default
instrument_ref str

Instrument MFID or slug

None
instrument_id str

Explicit instrument slug

None
include_metadata bool

Whether to include scientific metadata

False
include_owner bool

Resolve the owner into a public-safe user object (default: True)

True
instrument_mfid str

Explicit instrument MFID

None
instrument_name str

Removed in 4.0.0; passing it raises RemovedError.

None
include_members bool

Include the members, owner first, as members (ProjectMember records). The API returns members: None to callers who are not members.

False

Returns:

Type Description
Optional[Dict]

Dict or None: Instrument information if found, None otherwise

Raises:

Type Description
ValueError

If no reference or multiple references are provided

search(q, limit=20, include_owner=False, status=None, affiliation=None, owner_ref=None)

Fuzzy search across instruments. Available to all authenticated users.

Matches against instrument_name, instrument_type, and manufacturer (best score across the three).

Parameters:

Name Type Description Default
q str

Search term (min 3 chars). Typo-tolerant.

required
limit int

Max results (default 20, max 50).

20
include_owner bool

Resolve the owner into a public-safe user object.

False
status Optional[str]

Restrict results to active, maintenance, or decommissioned.

None
affiliation Optional[Union[str, Sequence[str]]]

'owner', 'maintainer' (editor or admin member), or 'member' (any role), to search only the caller's instruments.

None
owner_ref Optional[Union[str, Sequence[str]]]

Owner or owners (up to 10, any matches): unique_id, linked ORCID, username, or email.

None

Returns:

Type Description
List[Dict]

List[Dict]: Matching instrument records, ranked by relevance.

create(instrument, scientific_metadata=None)

Create a new instrument as an authenticated human caller.

Service accounts cannot create instruments. If the instrument already exists, this method returns the existing record.

Parameters:

Name Type Description Default
instrument Union[Instrument, Dict]

Instrument model or dict with instrument details. Required fields: instrument_id, instrument_name, and location. Owner defaults to the authenticated identity.

required
scientific_metadata Dict

Scientific metadata to attach after creation.

None

Returns:

Name Type Description
Dict Dict

Created (or existing) instrument object

Raises:

Type Description
ValueError

If instrument_id is missing

update(instrument_ref, **kwargs)

Partially update an instrument record.

Requires editor permission.

Parameters:

Name Type Description Default
instrument_ref str

Instrument unique identifier (MFID)

required
**kwargs Any

Fields to update. Accepted: instrument_id, instrument_name, location, manufacturer, model, instrument_type, description, other_id, other_id_source.

{}

Returns:

Name Type Description
Dict Dict

Updated instrument object

set_status(instrument_mfid, status)

Change an instrument lifecycle status.

Parameters:

Name Type Description Default
instrument_mfid str

Instrument unique identifier (MFID)

required
status str

One of active, maintenance, or decommissioned

required

Returns:

Name Type Description
Dict Dict

Updated instrument response

list_users(instrument_ref, limit=DEFAULT_LIMIT, offset=0, cursor=None)

List the instrument's members, highest role first, owner first.

Every member reads the datasets assigned to the instrument.

Returns:

Type Description
Optional[List[ProjectMember]]

List[ProjectMember] or None: None when the caller is not a member

Optional[List[ProjectMember]]

and not a platform administrator.

add_user(instrument_ref, user, role='viewer')

Add a member: 'viewer' reads the instrument's datasets, 'editor' also edits details, 'admin' also changes status, binds service accounts, and manages members.

Requires admin on the instrument; you cannot grant above your own role. user accepts an ORCID, MFID, or username; service accounts are bound with bind_service_account() instead.

Returns:

Type Description
List[ProjectMember]

List[ProjectMember]: The instrument's members after the change.

remove_user(instrument_ref, user)

Remove a member. Requires admin on the instrument, except to remove yourself. Returns the remaining members.

update_user_role(instrument_ref, user, role)

Change a member's role (same rules as add_user()). Returns the members.

list_service_accounts(instrument_mfid)

List service accounts bound to an instrument.

Parameters:

Name Type Description Default
instrument_mfid str

Instrument unique identifier (MFID)

required

Returns:

Type Description
List[ProjectMember]

List[ProjectMember]: Bound service accounts and their operator roles

bind_service_account(instrument_ref, service_account_ref)

Bind a service account as an operator of an instrument.

Requires admin on the instrument (its owner or an admin member). A bound service account gets contributor on every dataset assigned to the instrument.

Parameters:

Name Type Description Default
instrument_ref str

Instrument unique identifier (MFID)

required
service_account_ref str

Service account unique identifier (MFID)

required

Returns:

Type Description
List[ProjectMember]

List[ProjectMember]: The instrument's operator group members

unbind_service_account(instrument_ref, service_account_ref)

Remove a service account as an operator of an instrument.

Requires admin on the instrument (its owner or an admin member).

Parameters:

Name Type Description Default
instrument_ref str

Instrument unique identifier (MFID)

required
service_account_ref str

Service account unique identifier (MFID)

required

Returns:

Type Description
List[ProjectMember]

List[ProjectMember]: The instrument's operator group members

list_access(mfid)

List every principal with access to a resource.

Readable by anyone with a role on the resource (not through public access alone); the resource's capabilities.can_view_access says whether you can. Each grant's capabilities says whether you may remove it or change its role, and to which roles.

set_public(mfid)

Grant public viewer access to a resource.

set_private(mfid)

Revoke public access to a resource.

transfer_ownership(mfid, new_owner, confirm=False)

Preview or apply a resource ownership transfer.