Privileged API Reference

Warning

Classes on this page target privileged endpoints and require valid NMDCAuth credentials. They are intended for authorized users who need metadata submission, identifier minting, or staging workflows.

Authentication Support

NMDCAuth is required for all privileged classes on this page.

class nmdc_api_utilities.auth.NMDCAuth(client_id=None, client_secret=None, username=None, password=None, api_base_url='https://api.microbiomedata.org', env='')[source]

Bases: NMDCAPIClient

Authentication handler for NMDC API operations.

Parameters:

  • client_id (str | None, default: None) – The client ID for NMDC API authentication. See Notes for further details.

  • client_secret (str | None, default: None) – The client secret for NMDC API authentication. See Notes for further details.

  • username (str | None, default: None) – The username for NMDC API authentication. See Notes for further details.

  • password (str | None, default: None) – The password for NMDC API authentication. See Notes for further details.

  • api_base_url (str, default: 'https://api.microbiomedata.org') – The base URL of an instance of the NMDC Runtime API. By default, this is the base URL of the production instance.

  • env (str, default: '') – Deprecated. Use api_base_url instead. Previously used to specify the API environment (e.g., “prod”, “dev”).

Notes

Security Warning - your credentials should be stored in a secure location. Do not hard-code these values in your code; we recommend using environment variables.

You must provide either:

  • client_id and client_secret (for client credentials grant), OR

  • username and password (for password grant).

get_token()[source]

Get a valid access token, refreshing if necessary.

Return type:

str

has_credentials()[source]

Check if the credentials are passed in properly.

Return type:

bool

Authentication Requirement

Instantiate NMDCAuth and pass it to privileged classes:

from nmdc_api_utilities.auth import NMDCAuth
from nmdc_api_utilities.metadata import Metadata

auth = NMDCAuth(client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET")
metadata_client = Metadata(auth=auth)

Metadata Submission

class nmdc_api_utilities.metadata.Metadata(api_base_url='https://api.microbiomedata.org', auth=None, env='')[source]

Bases: NMDCAPIClient

Class to interact with the NMDC API metadata endpoints.

This class includes methods for interacting with endpoints for metadata management, including validation and submission. It is not intended for general/public use.

Parameters:

  • api_base_url (str, default: 'https://api.microbiomedata.org') – The base URL of the NMDC API.

  • auth (NMDCAuth | None, default: None) – An instance of the NMDCAuth class for authentication.

submit_json(json_records)[source]

Submits a json file to the NMDC metadata database via the NMDC Runtime API’s json_submit endpoint.

Parameters:

json_records (list[dict] | str) – The json records to be submitted. Can be passed in as a file path or list of dictionaries.

Returns:

The HTTP status code of the submission request.

Return type:

int

Raises:

Exception – If the submission fails.

validate_json(json_records)[source]

Validates a json file using the NMDC json validate endpoint.

If the validation passes, the method returns without any side effects.

Parameters:

json_records (list[dict] | str) – The json records to be validated. Can be passed in as a file path or list of dictionaries.

Returns:

The HTTP status code of the validation request.

Return type:

int

Raises:

Exception – If the validation fails.

Identifier Minting

class nmdc_api_utilities.minter.Minter(api_base_url='https://api.microbiomedata.org', auth=None, env='')[source]

Bases: NMDCAPIClient

Class to interact with the NMDC API to mint new identifiers.

Parameters:

  • api_base_url (str, default: 'https://api.microbiomedata.org') – The base URL of the NMDC API.

  • auth (NMDCAuth | None, default: None) – An instance of the NMDCAuth class for authentication.

mint(nmdc_type, count=1, client_id=None, client_secret=None)[source]

Mint new identifier(s) for a specified type of record.

Parameters:

  • nmdc_type (str) – The type of NMDC ID to mint (e.g., ‘nmdc:MassSpectrometry’, ‘nmdc:DataObject’).

  • count (int, default: 1) – The number of identifiers to mint.

  • client_id (str | None, default: None) – The client ID for authentication. Kept for backwards compatibility.

  • client_secret (str | None, default: None) – The client secret for authentication. Kept for backwards compatibility.

Returns:

If count is 1, returns a single minted identifier as a string. If count is greater than 1, returns a list of minted identifiers.

Return type:

str | list[str]

Raises:

  • RuntimeError – If the API request fails.

  • ValueError – If count is less than 1.

Notes

If client_id and client_secret are provided, a new instance of the NMDCAuth class will be created. The newest and preferred method for authentication is to use the NMDCAuth class directly.

Data Staging and Workflow Management

class nmdc_api_utilities.data_staging.JGISequencingProjectAPI(auth, api_base_url='https://api.microbiomedata.org', env='')[source]

Bases: NMDCAPIClient

Class to interact with the NMDC API to get JGI samples.

Parameters:

  • auth (NMDCAuth) – The NMDCAuth instance containing the credentials and API base URL for authentication.

  • api_base_url (str, default: 'https://api.microbiomedata.org') – The base URL of an instance of the NMDC Runtime API. By default, this is the base URL of the production instance.

  • env (str, default: '') – Deprecated. Use api_base_url instead. Previously used to specify the API environment (e.g., “prod”, “dev”).

create_jgi_sequencing_project(jgi_sequencing_project)[source]

Create a new JGI sequencing project in the NMDC database. For more information on available keys, visit the NMDC API Docs https://api.microbiomedata.org/docs#/Workflow%20management/create_sequencing_record_wf_file_staging_jgi_sequencing_projects_post

Parameters:

jgi_sequencing_project (dict) – The JGI sequencing project data to be created.

Returns:

The created JGI sequencing project record.

Return type:

dict

Raises:

Exception – If the creation fails.

get_jgi_sequencing_project_by_name(project_name)[source]

Get a specific JGI sequencing project by name.

Parameters:

project_name (str) – The name of the JGI sequencing project to retrieve.

Returns:

The JGI sequencing project record.

Return type:

dict

list_jgi_sequencing_projects(filter=None, max_page_size=20, fields='', all_pages=False)[source]

List JGI sequencing projects from the NMDC database.

Parameters:

  • filter (str | None, default: None) – Filter to apply to the API call.

  • max_page_size (int, default: 20) – The maximum number of items to return per page.

  • fields (str, default: '') – The fields to return.

  • all_pages (bool, default: False) – True to return all pages. False to return the first page.

Returns:

The list of JGI sequencing projects.

Return type:

list[dict[str, Any]]

class nmdc_api_utilities.data_staging.JGISampleSearchAPI(auth, api_base_url='https://api.microbiomedata.org', env='')[source]

Bases: NMDCAPIClient

Class to interact with the NMDC API to get JGI samples.

Parameters:

  • auth (NMDCAuth) – The NMDCAuth instance containing the credentials and API base URL for authentication.

  • api_base_url (str, default: 'https://api.microbiomedata.org') – The base URL of an instance of the NMDC Runtime API. By default, this is the base URL of the production instance.

  • env (str, default: '') – Deprecated. Use api_base_url instead. Previously used to specify the API environment (e.g., “prod”, “dev”).

insert_jgi_sample(jgi_sample)[source]

Insert JGI samples into the NMDC database. For more information on keys, visit the NMDC API Docs https://api.microbiomedata.org/docs#/Workflow%20management/create_jgi_sample_wf_file_staging_jgi_samples_post

Parameters:

jgi_sample (dict) – The JGI sample data to be inserted.

Returns:

The response from the insertion operation.

Return type:

dict

Raises:

Exception – If the insertion fails.

list_jgi_samples(filter=None, max_page_size=20, fields='', all_pages=False)[source]

Get a specific JGI sample by name.

Parameters:

  • filter (str | None, default: None) – Filter to apply to the API call.

  • max_page_size (int, default: 20) – The maximum number of items to return per page.

  • fields (str, default: '') – The fields to return.

  • all_pages (bool, default: False) – True to return all pages. False to return the first page.

Returns:

The list of JGI sample records.

Return type:

list[dict]

update_jgi_sample(jgi_file_id, jgi_sample)[source]

Update JGI samples in the NMDC database. For more information on available keys, visit the NMDC API Docs https://api.microbiomedata.org/docs#/Workflow%20management/update_jgi_samples_wf_file_staging_jgi_samples__jdp_file_id__patch

Parameters:

  • jgi_file_id (str) – The JGI file ID of the sample to be updated.

  • jgi_sample (dict) – The updated JGI sample data.

Returns:

The response from the update operation.

Return type:

dict

Raises:

Exception – If the update fails.

class nmdc_api_utilities.data_staging.GlobusTaskAPI(auth, api_base_url='https://api.microbiomedata.org', env='')[source]

Bases: NMDCAPIClient

Class to interact with the NMDC API for Globus tasks.

Parameters:

  • auth (NMDCAuth) – The NMDCAuth instance containing the credentials and API base URL for authentication.

  • api_base_url (str, default: 'https://api.microbiomedata.org') – The base URL of an instance of the NMDC Runtime API. By default, this is the base URL of the production instance.

  • env (str, default: '') – Deprecated. Use api_base_url instead. Previously used to specify the API environment (e.g., “prod”, “dev”).

create_globus_task(globus_task)[source]

Create a new Globus task in the NMDC database. For more information on available keys, visit the NMDC API Docs https://api.microbiomedata.org/docs#/Workflow%20management/create_globus_tasks_wf_file_staging_globus_tasks_post

Parameters:

globus_task (dict) – The Globus task data to be created.

Returns:

The created Globus task record.

Return type:

dict

Raises:

Exception – If the creation fails.

list_globus_tasks(filter=None, max_page_size=20, fields='', all_pages=False)[source]

Get Globus tasks from the NMDC database.

Parameters:

  • filter (str | None, default: None) – Filter to apply to the API call.

  • max_page_size (int, default: 20) – The maximum number of items to return per page.

  • fields (str, default: '') – The fields to return.

  • all_pages (bool, default: False) – True to return all pages. False to return the first page.

Returns:

The list of Globus task records.

Return type:

list[dict]

update_globus_task(globus_task_id, globus_task)[source]

Update a Globus task in the NMDC database. For more information on available keys, visit the NMDC API Docs https://api.microbiomedata.org/docs#/Workflow%20management/update_globus_tasks_wf_file_staging_globus_tasks__task_id__patch

Parameters:

  • globus_task_id (str) – The ID of the Globus task to be updated.

  • globus_task (dict) – The Globus task data to be updated.

Returns:

The updated Globus task record.

Return type:

dict

Raises:

Exception – If the update fails.