metabolomics-workbench-database

What it does

Guides an AI agent to interact with the Metabolomics Workbench REST API to look up metabolite IDs, discover studies, standardise names to RefMet, perform m/z precursor searches, and fetch gene/protein annotations. It specifies input-item constraints (e.g., compound inputs must avoid the name input and use alternatives), and outlines workflows for converting free text to a canonical RefMet name and then to full records.

How it works

• Use the REST base URL https://www.metabolomicsworkbench.org/rest for requests.
• For compounds, the agent should perform a two-step process: (1) call /refmet/match/{user_text} to obtain a refmet_name, then (2) call /refmet/name/{refmet_name}/all to fetch the full record that includes IDs like pubchem_cid and inchi_key. If available, optionally fetch compound details via /compound/pubchem_cid/{cid}/all/json.
• For exact compound retrieval, query /compound/{input_item}/{input_value}/all/json with input_item from allowed list (regno, formula, inchi_key, lm_id, pubchem_cid, hmdb_id, kegg_id, SMILES, abbrev).
• To normalise a name to RefMet and then fetch the full record, use /refmet/match/{user_text} followed by /refmet/name/{refmet_name}/all.
• Use /study/study_id/{id}/summary for single-study summaries and /study/refmet_name/{name}/summary to list studies by RefMet name, then traverse to full summaries as needed.
• For RefMet-based annotation of MS hits, call /moverz/{REFMET|LIPIDS|MB}/{mz}/{ion}/{tol}/txt and parse the returned TSV (no JSON).
• If filtering studies via metstat endpoints, switch to study/... with client-side filtering, assembling summaries with /study/study_id/{id}/summary.
• The workflow examples show code patterns for Python requests, including error handling, JSON parsing, and CSV/TSV parsing.

When to use it

• When searching metabolite records by PubChem CID, KEGG ID, InChIKey, HMDB ID, formula, or SMILES.
• When discovering studies by species, disease, institute, analysis_type, or polarity.
• When standardising metabolite names to RefMet nomenclature for cross-study integration.
• When identifying unknown compounds from MS m/z values with adduct-aware matching (moverz).
• When retrieving experimental metabolite tables from published studies.
• When querying gene/protein annotations linked to metabolomics pathways.
• When downloading raw mwTab files for local analysis.

What it can touch

• Uses the base URL https://www.metabolomicsworkbench.org/rest.
• Calls to /refmet/match, /refmet/name, /compound, /study, /moverz, /gene, and /protein endpoints.
• No authentication is required; the description notes public access.

Caveats

• The moverz endpoint returns TSV text, not JSON.
• The compound/name input is rejected; use alternative input_item values (e.g., pubchem_cid, kegg_id, inchi_key, etc.).
• The refmet/name endpoint requires the canonical RefMet name; for fuzzy matching, use refmet/match first.
• Some older endpoints (metstat/filter/…) are deprecated in favor of study/{context}/{value}/summary with client-side filtering.
• The description recommends using hmdb-database for local XML and pubchem-compound-search for general compound lookups.