API Reference¶
This section provides detailed documentation for the USNAN SDK API endpoints and their JSON responses.
Overview¶
The endpoints provide access to different data objects within NAN. In this initial release, that includes:
Datasets (also known as experiments) (
usnan.models.datasets.Dataset)Facilities (
usnan.models.facilities.Facility)Spectrometers (also known as spectrometers) (
usnan.models.spectrometers.Spectrometer)Probes (
usnan.models.probes.Probe)
Furthermore, some of these data objects have other data objects embedded inside of them. For example, a facility object has staff objects associated with it. These embedded objects are implemented as Python dataclasses in the SDK models and their JSON structure is documented in the respective endpoint sections below.
Dataset Fetch Endpoint¶
GET /nan/public/datasets/{dataset_id}- Retrieve a specific dataset by ID
JSON Response Structure:
{
"id": 0,
"classification": "string",
"dataset_name": "string",
"decoupling_sequence": "string",
"experiment_end_time": "string",
"experiment_name": "string",
"experiment_start_time": "string",
"facility_identifier": "string",
"identifier": "string",
"is_knowledgebase": true,
"is_locked": true,
"is_multi_receiver": true,
"is_non_uniform": true,
"mas_rate": 0.0,
"mixing_sequence": "string",
"mixing_time": 0.0,
"notes": "string",
"num_dimension": 0,
"num_dimension_collected": 0,
"number_in_set": 0,
"pi_name": "string",
"preferred": true,
"public_time": "string",
"published_time": "string",
"pulse_sequence": "string",
"sample_id": 0,
"sample_sparsity": 0.0,
"session_id": 0,
"solvent": "string",
"source": "string",
"spectrometer_identifier": "string",
"state": "string",
"tags": ["string"],
"temperature_k": 0.0,
"time_shared": true,
"title": "string",
"version": "string",
"z0_drift_correction": true,
"dimensions": [
{
"dimension": 0,
"nucleus": "string",
"is_direct": true,
"spectral_width_ppm": 0.0,
"maximum_evolution_time": 0.0,
"num_points": 0
}
],
"versions": [
{
"id": 0,
"version": 0
}
]
}
Response Fields:
id(integer) - The unique ID of the dataset. Note that this ID refers to a specific version of a dataset. (Which may be the original version.)identifier(string) - The identifier of the dataset more broadly - allowing access to all versions of the dataset. This is used to generate the unique ARK records for a dataset.classification(string) - An optional classification value entered by the user. Chosen from the following:"Calibration experiment", "Failed-sample related", "Failed-instrument related", "Failed-setup related", "Successful experiment", "Test experiment"dataset_name(string) - The name of the dataset, which can be edited by the user. If the user has edited the name, this will be a more human-readable name than the experiment_name which is set automatically and is immutable.decoupling_sequence(string) - The name of the decoupling sequence used in the experiment.experiment_end_time(string) - The end date and time (with timezone) of the experiment.experiment_name(string) - The name of the experiment as ran on the spectrometer. May not be edited.experiment_start_time(string) - The start date and time (with timezone) of the experiment.facility_identifier(string) - The identifier of the facility the experiment was ran in.is_knowledgebase(boolean) - Whether or not the dataset has been marked as a knowledgebase.is_locked(boolean) - A boolean (yes/no) describing if the sample was locked on a deuterated solvent during the experiment collection.is_multi_receiver(boolean) - [Add description]is_non_uniform(boolean) - A boolean (yes/no) if the experiment was collected with non-uniform sampling.mas_rate(float) - The magic angle spinning rate in kHz, if applicable.mixing_sequence(string) - The name of the mixing sequence used in the experiment, if applicable.mixing_time(float) - The lenght of time (seconds) of the applied mixing sequence, if applicable.notes(string) - Arbitrary text notes on the dataset entered by the user.num_dimension(integer) - The total number of dimensions defined in the pulse program.num_dimension_collected(integer) - The number of dimensions that were actually collected during acquisition.number_in_set(integer) - Often multiple experiments are ran with the same experiment_name but only one is the actual experiment, whereas the others are calibrations or tests. This indicates how many experiments were ran in a row with the same experiment_name. Usually, only one of these experiments will be marked as preferred - the non-preferred experiments are hidden by default.preferred(boolean) - Whether or not the dataset has been marked as preferred out of a set. See number_in_set above.pi_name(string) - The name of the principal investigator who has authority over the dataset.public_time(string) - The date and time (with timezone) the dataset will become or has become public. For unauthenticated requests, this will always be in the past. Authenticated users may see datasets with future public times if they have permission to access them.published_time(string) - The date and time (with timezone) that the dataset was published. Publishing creates an immutable copy of the metadata and data of the dataset and causes an ARK record to be issued. Published datasets are issued a version number to allow individual published versions to be referenced.pulse_sequence(string) - The name of the pulse program used to collect the experiment.sample_id(integer) - The ID of the sample linked to the dataset.sample_sparsity(float) - Percentage of acquired points (0–100%). A value of 100% indicates a fully sampled dataset. A value of less then 100% indicates a non-uniformly sampled (NUS) experiment.session_id(integer) - A unique session identifier. This can be used to locate other experiments ran before or after a given experiment on the same spectrometer by the same user.solvent(string) - The deuterated solvent used when collecting the experiment.source(string) - Whether the dataset was captured directly by NDTS (NDTS-auto), whether it was manually uploaded later from the spectrometer by a facility manager (NDTS-manual), or whether it was uploaded via the web GUI by an arbitrary user (NAN-arbitrary)spectrometer_identifier(string) - The identifier of the spectromter the experiment was ran on. Can be used to look up the spectrometer information.state(string) - Identifies the experiment as solid state or solution state.tags(string[]) - Arbitrary text tags associated with the experiment for user convenience.temperature_k(float) - The temperature the spectrometer recorded the experiment was ran at.time_shared(boolean) - A pulse sequence is designed to generate multiple independent spectra within a single experiment by alternating transfer pathways.title(string) - The title of the experiment. Set by the user, this is a formal title for a dataset.version(string) - The version of the dataset. Null for original datasets, set to a non-zero increasing number for published datasets.z0_drift_correction(boolean) - States the user defined Z0 drift correction for an experiment collected in an unlocked state.
Dimension Object Fields:
dimension(integer) - Identifies the dimension order.nucleus(string) - The nucleus observed in this dimension (e.g., “1H”, “13C”).is_direct(boolean) - Indicates whether this dimension is the direct detection dimension.spectral_width_ppm(float) - The spectral width of this dimension in parts per million (ppm).maximum_evolution_time(float) - The maximum evolution time for this dimension (in seconds).num_points(integer) - The number of acquired points in this dimension.
Version Object Fields:
id(integer) - The identifier of the dataset with the version specified.version(integer) - The version of the dataset with the id above.
The version object allows you to look up other versions of a given dataset.
Dataset Search Endpoint¶
GET /nan/public/datasets/search- Search for datasets using various filters
Parameters:
filters(json) - A dictionary of search filter configurations, JSON encoded. Details below.records(integer) - The number of records to return at a time. Defaults to 100.offset(integer) - An integer offset into the results. Defaults to 0.sort_field(string) - The name of the field to sort by. Must match one of the fields in the Experiment response.sort_order(‘ASC’ or ‘DESC’) - Specifies whether to sort by the sort_field in ascending or descending order.
Some examples of the filters parameter, prior to being stringified:
{id: [{value: 363067, matchMode: 'equals', operator: 'OR'}, {value: 363068, matchMode: 'equals', operator: 'OR'}]}- Filters where the dataset ID has the exact value 363067 OR 363068.{is_knowledgebase: [{value: true, matchMode: 'equals'}], num_dimension: [{value: 2, match_mode: 'greaterThan'}]}- Filters where the dataset is a knowledgebase and has at least 2 dimensions.
These filter types an options are documented fully in Dataset Filtering Guide.
JSON Response Structure:
{
"last_page": "boolean",
"experiments": "Dataset[]"
}
last_page(boolean) - True when this response contains the last page of results for the query. When false, more records can be obtained by repeating the query with a higher offset value.experiments(Dataset[]) - An array of dataset objects. (See the structure of this object in the Dataset Fetch Endpoint documentation.)
Facilities Endpoints¶
GET /nan/public/facilities- List all facilitiesGET /nan/public/facilities/{facility_id}- Retrieve a specific facility by ID
JSON Response Structure:
{
"identifier": "string",
"long_name": "string",
"short_name": "string",
"description": "string",
"institution": "string",
"url": "string",
"color": "string",
"logo": "string",
"services": [
{
"service": "string",
"description": "string"
}
],
"webpages": [
{
"urltype": "string",
"url": "string"
}
],
"staff": [
{
"first_name": "string",
"last_name": "string",
"middle_initial": "string",
"work_phone": "string",
"mobile_phone": "string",
"email": "string",
"roles": ["string"],
"responsibilities": ["string"],
"expertise": ["string"]
}
],
"contacts": [
{
"name": "string",
"work_phone": "string",
"mobile_phone": "string",
"email": "string",
"details": "string",
"responsibilities": ["string"]
}
],
"addresses": [
{
"address_type": ["string"],
"address1": "string",
"address2": "string",
"address3": "string",
"city": "string",
"state": "string",
"zipcode": "string",
"zipcode_ext": "string",
"country": "string"
}
]
}
Response Fields:
The core facility information.
identifier(string) - The unique identifier for the facility. Choosen by administrators rather than being randomly assigned.long_name(string) - A long name for the facility, including the center name.short_name(string) - A shorter name for the facility.description(string) - A description of the facility.institution(string) - The name of the institution that the facility is located at.url(string) - The official URL for the facility.color(string) - A hex color code used to style the facilities pages.logo(string) - The facility logo in SVG format.services(Service[]) - See belowwebpages(Webpage[]) - See belowstaff(Staff[]) - See belowcontacts(Contact[]) - See belowaddresses(Address[]) - See below
Service Fields:
A service the facility provides.
service(string) - A string describing the type of service provided. Valid values are one of the following:"Analysis", "Data Processing", "Experiment Setup", "Remote Access", "Rotor Packing", "Sample Preparation", "Self Service", "Shipping and Handling", "Consultation", "Training"description(string) - Additional information about the service provided at this facility.
Webpage Fields:
A web page assosciated with the facility.
urltype(string) - A string describing the type of URL provided. Valid values are one of the following:"Contact", "Facility Access", "Overview", "Policy", "Rates", "Research", "Service", "Spectrometers"url(string) - The URL to the web page.
Staff Fields:
A staff member at the facility.
first_name(string) - The staff member’s given name(s).last_name(string) - The staff member’s family name(s).middle_initial(string) - The staff member’s middle initial(s).work_phone(string) - The staff member’s work phone number.mobile_phone(string) - The staff member’s mobile phone number.email(string) - The staff member’s e-mail.roles(string[]) - The staff member’s roles. A list of one or more of the following strings:"Administrator", "Director", "Engineer", "FacilityManager", "Researcher", "Technician", "Approver"responsibilities(string) - The staff member’s responsibilties. A list of one or more of the following strings:"Administrative Services", "Equipment Maintenance", "Experiment Support", "Sample Shipping and Handling", "Scheduling"expertise(string) - The staff member’s expertise. A list of one or more of the following strings:"Bruker", "DNA/RNA", "Material", "Metabolomics", "Protein", "Pulse Sequence Programming", "Rotor Packing", "Small Molecule", "Solid State", "Solution", "Varian", "Carbohydrates"
Contact Fields:
A contact at the facility, who may or may not also be a staff member.
name(string) - The contact’s name.work_phone(string) - The contact’s work phone number.mobile_phone(string) - The contact’s mobile phone.email(string) - The contact’s e-mail address.details(string) - Details about the contact, or under what circumstances they are the appropriate contact.responsibilities(string[]) - The staff member’s responsibilties. A list of one or more of the following strings:"Administrative Services", "Equipment Maintenance", "Experiment Support", "Sample Shipping and Handling", "Scheduling"
Address Fields:
An address associated with the facility.
address_type(string[]) - The type of the address record. One or more of the following strings:"Physical", "Mailing", "Shipping"address1(string) - The first line of the facility address.address2(string) - The second line of the facility address.address3(string) - The third line of the facility address.city(string) - The city the address is located at.state(string) - The state the address is located at.zipcode(string) - The zip code of the address.zipcode_ext(string) - The zip code extension of the address.country(string) - The country of the address.
Spectrometers Endpoints¶
GET /nan/public/instruments- List all spectrometers/instrumentsGET /nan/public/instruments/{instrument_id}- Retrieve a specific spectrometer by ID
JSON Response Structure:
{
"identifier": "string",
"name": "string",
"year_commissioned": 0,
"status": "string",
"is_public": true,
"rates_url": "string",
"magnet_vendor": "string",
"field_strength_mhz": 0.0,
"bore_mm": 0.0,
"is_pumped": true,
"console_vendor": "string",
"model": "string",
"serial_no": "string",
"year_configured": 0,
"channel_count": 0,
"receiver_count": 0,
"operating_system": "string",
"version": "string",
"sample_changer_id": 0,
"facility_identifier": "string",
"sample_changer_default_temperature_control": true,
"sample_changer": {
"model": "string",
"vendor": "string",
"min_temp": 0.0,
"max_temp": 0.0,
"num_spinners": 0,
"num_96_racks": 0
},
"software": {
"software": "string",
"versions": [
{
"version": "string",
"installed_software": ["string"]
}
]
},
"installed_probe": {
"identifier": "string"
},
"compatible_probes": [
{
"identifier": "string"
}
],
"install_schedule": [
{
"probe_identifier": "string",
"install_start": "string"
}
],
"field_drifts": [
{
"rate": 0.0,
"recorded": "string"
}
]
}
Response Fields:
identifier(uuid) - A unique identifier for the spectrometer.name(string) - The facility assigned name of the spectrometer.year_commissioned(integer) - The calendar year when the spectrometer was first put into operation.status(string) - The current status of the instrument. One of the following:"Decommissioned", "Operational", "Under Repair"is_public(boolean) - Whether the instrument is public. Will always be true for the public (unauthenticated) API.rates_url(string) - A hyperlink to a page with information about usage rates.magnet_vendor(string) - The vendor of the spectrometer magnet. One of the following:"Agilent/Varian", "Bruker", "JEOL", "Q One", "Tech MAG"field_strength_mhz(integer) - The field strength of the spectrometer in megahertzbore_mm(integer) - The inner diameter of the magnet bore, measured in millimeters. This defines the maximum probe and sample sizes the spectrometer can accommodate.is_pumped(boolean) - [Add description]console_vendor(string) - The vendor of the spectrometer console. One of the following:"Agilent/Varian", "Bruker", "JEOL", "Q One", "Tech MAG"model(string) - The model of the spectrometer.serial_no(string) - The serial number of the spectrometer.year_configured(integer) - The most recent year the spectrometer was configured or upgraded.channel_count(integer) - The number of independent transmitter channels available for excitation.receiver_count(integer) - The number of independent receivers available for signal acquisition.operating_system(string) - The operating system of the spectrometer console. One of the following:"Windows", "RedHat", "CentOS", "Ubuntu", "Alma"version(string) - The version of the operating system of the spectrometer console.sample_changer_id(integer) - The identifier of the sample changer in use.facility_identifier(string) - The identifier of the facility the spectrometer is located in.sample_changer_default_temperature_control(string) - The temperature control of the sample changer. One of the following:"Cooled", "Heated", "Room Temperature"sample_changer(SampleChanger) - See below.software(Software) - See below.installed_probe(ProbeStub) - See below.compatible_probes(ProbeStub[]) - See below
Sample Changer Object Fields:
model(string) - The model of the sample changer.vendor(string) - The vendor of the sample changer.min_temp(string) - The minimum temperature the sample changer can operate at.max_temp(string) - The maximum temperature the sample changer can operate at.num_spinners(string) - Number of sockets available for spinners.num_96_racks(string) - Number of sockets available for 96-tube racks.
Software Object Fields:
software(string) - The software package installed on the spectrometer.versions(SoftwareVersion[]) - The versions of the software package installed on the spectrometer.
Software Version Object Fields:
version(string) - The version number of the installed softwareinstalled_software(string[]) - An array of features of the installed software version.
Probe Stub Object Fields:
identifier(uuid) - The identifier of a probe. Can be used to look up the probe using the probes endpoint.
Install Schedule Object Fields:
identifier(uuid) - The identifier of the probe that was or will be installed on the install_start date.install_start(string) - A date with time and timezone that the probe was or will be installed.
Field Drift Object Fields:
rate(string) - The measured rate of magnetic field drift in Hz per hour.recorded(string) - The date the rate was recorded.
Probes Endpoints¶
GET /nan/public/probes- List all probesGET /nan/public/probes/{probe_id}- Retrieve a specific probe by ID
JSON Response Structure:
{
"identifier": "string",
"status": "string",
"status_detail": "string",
"kind": "string",
"vendor": "string",
"model": "string",
"serial_number": "string",
"cooling": "string",
"sample_diameter": 0.0,
"max_spinning_rate": 0.0,
"gradient": true,
"x_gradient_field_strength": 0.0,
"y_gradient_field_strength": 0.0,
"z_gradient_field_strength": 0.0,
"h1_fieldstrength_mhz": 0.0,
"min_temperature_c": 0.0,
"max_temperature_c": 0.0,
"facility_identifier": "string",
"facility_short_name": "string",
"facility_long_name": "string",
"installed_on": {
"spectrometer_identifier": "string",
"install_start": "string"
},
"channels": [
{
"ch_number": 0,
"amplifier_cooled": true,
"inner_coil": "string",
"outer_coil": "string",
"min_frequency_nucleus": 0.0,
"max_frequency_nucleus": 0.0,
"broadband": true,
"nuclei": [
{
"nucleus": "string",
"sensitivity_measurements": [
{
"is_user": true,
"sensitivity": 0.0,
"measurement_date": "string",
"name": "string",
"composition": "string"
}
]
}
]
}
]
}
Response Fields:
identifier(uuid) - The unique identifier for the probe.status(string) - The operational status of the probe. One of the following values:"Decommissioned", "Operational", "Under Repair"status_detail(string) - Any additional details about the probe status, like when repairs are expected to be completed.kind(string) - The type of probe. One of the following values:"Solid State", "Solution"vendor(string) - The probe vendor.model(string) - The probe model.serial_number(string) - The probe serial number.cooling(string) - How the probe is cooled, if it is cooled. One of the following values:"Helium", "Nitrogen", "Room Temp"sample_diameter(string) - The diameter of the sample that the probe can accommodate.max_spinning_rate(string) - The maximum spinning rate (in kHz) supported by the probe rotor for MAS experiments.gradient(string) - [Add description]x_gradient_field_strength(string) - The maximum gradient field strength along the X-axis in G/cm.y_gradient_field_strength(string) - The maximum gradient field strength along the Y-axis in G/cm.z_gradient_field_strength(string) - The maximum gradient field strength along the Z-axis in G/cm.h1_fieldstrength_mhz(string) - The proton resonance frequency in MHz corresponding to the field strength the probe is designed for.min_temperature_c(string) - The minimum temperature the probe can operate at.max_temperature_c(string) - The maximum temperature the probe can operate at.facility_identifier(string) - The unique identifier of the facility the probe is located at.installed_on(InstalledOn) - See belowchannels(Channel[]) - See below
Installed On Object Fields:
spectrometer_identifier(uuid) - The identifier of the spectrometer that the probe is installed on.install_start(string) - The date, time, and timezone that the probe was installed on the spectrometer.
Channel Object Fields:
ch_number(integer) - [Add description]amplifier_cooled(boolean) - [Add description]inner_coil(boolean) - [Add description]outer_coil(boolean) - [Add description]min_frequency_nucleus(string) - [Add description]max_frequency_nucleus(string) - [Add description]broadband(boolean) - [Add description]nuclei(Nucleus[]) - See below
Nucleus Object Fields:
nucleus(string) - [Add description]sensitivity_measurements(SensitivityMeasurement[]) - See below
Sensitivity Measurement Object Fields:
is_user(string) - [Add description]sensitivity(string) - [Add description]measurement_date(string) - The date, time, and timezone that the sensitivity measurement was taken.name(string) - [Add description]composition(string) - [Add description]