ScholarMuse DocsAPI reference
Every ScholarMuse tool you can call over REST, with its arguments, discipline pack and credits per call.
This page lists every tool with the arguments it accepts. It is generated from the same definitions the server runs, so it always matches the live API. For authentication, the response format and errors, see REST API.
The same information is available to programs:
GET /api/v1returns the list of tools.GET /api/v1/<tool>returns one tool with the JSON Schema of its arguments./api/v1/openapi.jsonis an OpenAPI 3.1 description of the whole API, which tools such as Postman can import.
list_capabilities
List every ScholarMuse capability with its tools, discipline pack and data sources. Call this first to see what you can do for the user.
POST /api/v1/list_capabilities · Pack: General research · 0 credits per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
discipline | "general" | "life" | "chem" | "earth" | "astro" | "humanities" | no | Only list capabilities in this discipline pack. |
create_figure
Generate a publication-ready scientific figure (mechanism or pathway diagram, workflow, study design, graphical abstract, schematic) from a description. Returns an image URL, or a figure_id to fetch with get_figure if it is still rendering. Not for plots of numeric data — write plotting code for those.
POST /api/v1/create_figure · Pack: General research · 0 credits per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
description | string | yes | What the figure shows: the entities, their relationships and the order of events. Be specific and scientifically precise. |
kind | "mechanism" | "workflow" | "graphical_abstract" | "schematic" | "poster_panel" | no | Figure type. Default: schematic. |
style | "nature" | "cell" | "minimal_line" | "flat_color" | "textbook" | no | Visual style. Default: nature. |
labels | string[] | no | Exact text labels to appear in the figure. |
aspect_ratio | "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | no | Default 16:9 for graphical abstracts and workflows, otherwise 4:3. |
edit_figure
Change a figure made with create_figure using a plain-language instruction (e.g. "make the arrows thicker", "rename the label X to Y"). Returns a new image; the original is kept.
POST /api/v1/edit_figure · Pack: General research · 0 credits per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
figure_id | string | yes | The figure_id returned by create_figure, edit_figure or get_figure. |
instruction | string | yes | What to change. One or two changes per call work best. |
get_figure
Fetch a figure by figure_id: returns the image URL when it is ready, or tells you it is still rendering.
POST /api/v1/get_figure · Pack: General research · 0 credits per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
figure_id | string | yes | The figure_id returned by create_figure or edit_figure. |
search_papers
Search real scholarly papers across OpenAlex, PubMed / Europe PMC, arXiv, INSPIRE-HEP and ERIC, de-duplicated, each source in its own relevance order. Returns DOI, authors, year, venue, citation count and open-access link. Use this instead of recalling references from memory.
POST /api/v1/search_papers · Pack: General research · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Topic, keywords or a natural-language question. |
year_from | integer | no | Earliest publication year. |
year_to | integer | no | Latest publication year. |
open_access_only | boolean | no | Only papers with a free full text. |
sources | string[] | no | Limit to these source ids: openalex, pubmed, arxiv, inspire-hep, eric, crossref, dblp. Default: openalex, pubmed and arxiv. Add eric for education research, inspire-hep for high-energy physics, dblp for computer science. |
limit | integer | no | Results to return (default 10). |
get_paper
Look up one paper by DOI, PMID ("pmid:123"), PMCID, arXiv id ("arxiv:1706.03762") or OpenAlex id. Returns verified metadata, abstract, citation count, retraction flag and an open-access link when one exists.
POST /api/v1/get_paper · Pack: General research · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
id | string | yes | DOI (10.xxxx/… or a doi.org URL), pmid:12345, PMC12345, arxiv:2301.01234 (or a bare arXiv id), or an OpenAlex id (W…). |
lookup_gene_protein
Resolve a gene symbol, gene name, UniProt accession or Ensembl gene id across NCBI Gene, Ensembl and UniProt and return one record: ids, name, summary and function, chromosome location, protein length, InterPro domains, Reactome pathways and top STRING interaction partners. Use it for verified gene/protein facts instead of recalling them. Research data lookup, not medical advice.
POST /api/v1/lookup_gene_protein · Pack: Life sciences & medicine · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Gene symbol (TP53), gene or protein name, UniProt accession (P04637) or Ensembl gene id (ENSG00000141510). |
organism | string | no | Organism name or NCBI taxon id, e.g. "mouse", "Danio rerio", "10090". Default: human (9606). |
include | "domains" | "pathways" | "interactions"[] | no | Extra sections to fetch: domains (InterPro), pathways (Reactome), interactions (STRING). Default: all. |
get_structure
Find 3D structures for a protein: experimental entries from RCSB PDB (method, resolution, release date, organism, mmCIF/PDB download links) plus the AlphaFold DB predicted model (mean pLDDT, version) for the UniProt accession. Pass a PDB id or UniProt accession as `id`, or a protein/gene name as `query`. Research data lookup, not medical advice.
POST /api/v1/get_structure · Pack: Life sciences & medicine · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
id | string | no | PDB id (e.g. 1M17) or UniProt accession (e.g. P00533). |
query | string | no | Protein or gene name when no id is known, e.g. "EGFR" or "hemoglobin". |
limit | integer | no | Experimental structures to return (default 10). |
search_clinical_trials
Search the ClinicalTrials.gov registry by condition, intervention, phase, recruitment status and country. Returns NCT id, title, status, phase, conditions, interventions, sponsor, enrollment, dates, primary outcomes and the registry URL. Use it to find or verify registered studies. Registry data for research, not medical advice or a recommendation to enrol.
POST /api/v1/search_clinical_trials · Pack: Life sciences & medicine · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
condition | string | no | Disease or condition, e.g. "heart failure". |
intervention | string | no | Drug, device or procedure, e.g. "semaglutide". |
phase | integer | no | Trial phase: 1, 2, 3 or 4. |
status | string | no | Overall status: recruiting, not_yet_recruiting, active_not_recruiting, completed, terminated, suspended, withdrawn, enrolling_by_invitation or unknown. |
country | string | no | Country with a study site, in English, e.g. "Germany" or "United States". |
query | string | no | Free text for anything else (sponsor, outcome, NCT id, keywords). |
limit | integer | no | Results to return (default 10). |
lookup_drug
Look up a drug or compound by name or ChEMBL id. Returns ChEMBL facts (ChEMBL id, max clinical phase, molecule type, formula, weight), curated mechanisms and targets, the most frequently reported adverse-event terms from openFDA FAERS (spontaneous report counts, not incidence or risk) and FDA label highlights (indications, whether a boxed warning exists). Research data lookup, not medical advice.
POST /api/v1/lookup_drug · Pack: Life sciences & medicine · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
name | string | yes | Drug name (generic, brand or research code) or a ChEMBL id such as CHEMBL941. |
include | "targets" | "adverse_events" | "label"[] | no | Sections to fetch: targets (ChEMBL mechanisms), adverse_events (openFDA FAERS), label (FDA label). Default: all. |
search_expression_data
Gene expression lookups: pass `gene` for GTEx median expression (TPM) across human tissues, highest tissues first; pass `query` to search NCBI GEO for expression datasets (series accession, title, organism, sample count, platform, date, URL). Both can be used in one call. Research data lookup, not medical advice.
POST /api/v1/search_expression_data · Pack: Life sciences & medicine · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
gene | string | no | Human gene symbol or Ensembl gene id for GTEx tissue expression, e.g. "ALB". |
query | string | no | Keywords for a GEO dataset search, e.g. "single cell lung fibrosis". |
organism | string | no | Limit GEO results to an organism (scientific name, e.g. "Mus musculus"). GTEx is human only. |
limit | integer | no | GEO series to return (default 10). |
lookup_compound
Look up one chemical compound in PubChem by name, CAS number, SMILES, InChIKey or CID. Returns formula, molecular weight, SMILES, InChIKey, XLogP, H-bond counts, TPSA, synonyms, a 2D structure image URL and the ChEBI definition and roles when available. Use it instead of recalling chemical properties from memory.
POST /api/v1/lookup_compound · Pack: Chemistry & materials · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Compound name, CAS number (58-08-2), SMILES, InChIKey or PubChem CID (2519). |
lookup_material
Find crystalline materials by formula, element set or material id across the Materials Project and OQMD (DFT-computed band gap, formation energy, stability) and the Crystallography Open Database (experimental structures with CIF download). Returns space group, lattice parameters and source links for each entry.
POST /api/v1/lookup_material · Pack: Chemistry & materials · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
formula | string | no | Chemical formula, e.g. TiO2 or LiFePO4. |
elements | string[] | no | Element symbols; returns materials made of exactly these elements, e.g. ["Ti","O"]. |
material_id | string | no | Materials Project id (mp-2657) or COD id (cod-1010942 or the 7-digit number). |
stable_only | boolean | no | Only thermodynamically stable computed phases (on the convex hull). Skips COD, which has no energies. |
limit | integer | no | Entries to return (default 10). |
search_grants
Search funded research projects at NIH (RePORTER), NSF and UKRI by topic, investigator, institution or year. Returns one record per project with project number, PI, organisation, funder, dates, amount and abstract. Use it to find who funds a topic or what a lab is funded for.
POST /api/v1/search_grants · Pack: General research · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Research topic or keywords, e.g. "CAR-T resistance". |
funder | "nih" | "nsf" | "ukri" | no | Limit to one funder. Default: all three. |
pi_name | string | no | Principal investigator name, e.g. "Carl June". |
organization | string | no | Awardee institution name, e.g. "Stanford University". |
year_from | integer | no | Earliest fiscal year (NIH) or start year (NSF, UKRI). |
year_to | integer | no | Latest fiscal year (NIH) or start year (NSF, UKRI). |
limit | integer | no | Projects to return (default 10). |
search_datasets
Search research datasets across Zenodo, Dryad, Harvard Dataverse, Hugging Face and DataCite, de-duplicated by DOI. Returns DOI, creators, year, repository, description, size or format when known, and the licence of the dataset itself. Use it to find data to reuse or cite.
POST /api/v1/search_datasets · Pack: General research · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Topic or keywords, e.g. "urban tree canopy". |
sources | "zenodo" | "dryad" | "dataverse" | "huggingface" | "datacite"[] | no | Limit to these repositories. Default: all. |
limit | integer | no | Datasets to return (default 10). |
find_series
Find official statistical series and indicators (GDP, CPI, unemployment, population, life expectancy…) in FRED, World Bank, IMF, OECD, Eurostat, BLS, US Census and Our World in Data. Returns candidates with a seriesId to pass to get_series. Name the country in the query, e.g. "GDP per capita China".
POST /api/v1/find_series · Pack: General research · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | What to measure and where, e.g. "US unemployment rate" or "life expectancy Japan". |
sources | "fred" | "world-bank" | "bls" | "oecd" | "eurostat" | "imf" | "owid" | "census"[] | no | Limit to these sources: fred, world-bank, imf, oecd, eurostat, bls, census, owid. Default: all. |
limit | integer | no | Candidates to return (default 10). |
get_series
Fetch the observations of one official statistical series by the seriesId returned by find_series (e.g. "world-bank:NY.GDP.PCAP.CD?country=CHN", "bls:LNS14000000"). Returns title, units, frequency, geography and dated values. Use it whenever you need real numbers instead of remembered ones.
POST /api/v1/get_series · Pack: General research · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
series_id | string | yes | A seriesId from find_series, in the form "<source>:<id>" with optional "?dimension=CODE" parts. |
start | string | no | First period to return: a year (2015) or ISO date (2015-06 or 2015-06-01). |
end | string | no | Last period to return: a year or ISO date. |
country | string | no | ISO country code (CHN or CN) for per-country sources: world-bank, imf, owid, oecd, eurostat. Overrides the country in series_id. |
verify_references
Check a reference list against Crossref and OpenAlex. For each reference returns a status (verified, corrected, not_found, uncertain), the real metadata of the matched paper, the fields that differ (year, pages, DOI, journal, first author) and a retraction flag. Use it to catch invented or wrong citations before a manuscript goes out.
POST /api/v1/verify_references · Pack: General research · 2 credits per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
references | any | yes | The reference list: one block of text in any citation style or BibTeX, or an array with one reference per item. At most 50 references per call. |
check_retractions
Check DOIs for retractions, corrections and expressions of concern using Crossref (which carries the Retraction Watch database) and the OpenAlex retraction flag. Returns one record per DOI with the notice DOI, date and source. Pass DOIs, or a reference list from which DOIs are extracted.
POST /api/v1/check_retractions · Pack: General research · 2 credits per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
dois | string[] | no | DOIs to check (10.xxxx/… or doi.org URLs), at most 100. |
references | string | no | Text containing DOIs, such as a reference list. Only references that include a DOI are checked. |
journal_info
Look up a journal by name or ISSN in OpenAlex and DOAJ. Returns publisher, ISSNs, open-access status, whether it is listed in DOAJ, article processing charge, works and citation counts, h-index, homepage and plain-language signals. Use it to check a journal before submitting or citing. Does not return the Journal Impact Factor.
POST /api/v1/journal_info · Pack: General research · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
journal | string | yes | Journal name (e.g. "PLOS ONE") or ISSN (e.g. "1932-6203"). |
get_weather_history
Daily or monthly historical weather for any point on Earth from 1981 onward (NASA POWER, satellite and reanalysis based, about 50 km grid): temperature, precipitation, humidity, wind speed and solar radiation. Use it for climate context of a field site or study period; it is gridded model data, not a weather-station record.
POST /api/v1/get_weather_history · Pack: Earth & environment · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
latitude | number | yes | Latitude in decimal degrees (north positive). |
longitude | number | yes | Longitude in decimal degrees (east positive). |
start | string | yes | First day, YYYY-MM-DD, not before 1981-01-01. |
end | string | yes | Last day, YYYY-MM-DD. |
variables | "temperature_max" | "temperature_min" | "temperature_mean" | "precipitation" | "relative_humidity" | "wind_speed" | "solar_radiation"[] | no | Variables to return. Default: temperature_max, temperature_min, temperature_mean, precipitation. |
aggregate | "daily" | "monthly" | no | daily (default, at most 2,000 days per call) or monthly means for long periods. |
search_earthquakes
Search the USGS global earthquake catalogue by area, magnitude and date. Returns magnitude, time (UTC), place, coordinates, depth and the USGS event page for each event.
POST /api/v1/search_earthquakes · Pack: Earth & environment · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
latitude | number | no | Centre latitude; use together with longitude. |
longitude | number | no | Centre longitude; use together with latitude. |
radius_km | number | no | Search radius around the centre (default 100 km). |
min_magnitude | number | no | Smallest magnitude to include. |
start | string | no | Earliest date, YYYY-MM-DD (UTC). Default: 30 days ago. |
end | string | no | Latest date, YYYY-MM-DD (UTC). Default: now. |
limit | integer | no | Events to return (default 20). |
order | "time" | "magnitude" | no | Newest first (time, default) or largest first. |
get_water_data
Daily mean streamflow, gage height or water temperature from a USGS monitoring site in the United States, or a list of sites in a state or bounding box when no site number is given. Use the site list first if you do not know the site number.
POST /api/v1/get_water_data · Pack: Earth & environment · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
site | string | no | USGS site number, e.g. 01646500 (Potomac River near Washington, DC). |
state | string | no | US state to list sites in: two-letter code (MD) or full name. |
bbox | number[] | no | Bounding box to list sites in: [west, south, east, north] in decimal degrees. |
parameter | "streamflow" | "gage_height" | "water_temperature" | no | What to measure (default streamflow). |
start | string | no | First day, YYYY-MM-DD. Default: 30 days before end. |
end | string | no | Last day, YYYY-MM-DD. Default: today. |
limit | integer | no | Sites to list when no site is given (default 20). |
search_species_occurrence
Find where and when a species has been recorded, from GBIF. Resolves a scientific or common name to a taxon, then returns the total record count and georeferenced occurrence records (coordinates, date, country, dataset, licence). Only CC0 and CC BY records are returned.
POST /api/v1/search_species_occurrence · Pack: Earth & environment · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
species | string | yes | Scientific name (Danaus plexippus) or common name (monarch butterfly). |
country | string | no | Two-letter ISO 3166 country code, e.g. MX. |
year_from | integer | no | Earliest year of the record. |
year_to | integer | no | Latest year of the record. |
has_coordinates | boolean | no | Only records with coordinates (default true). |
limit | integer | no | Records to return (default 50). |
get_air_quality
Measured air quality near a point from OpenAQ: the nearest monitoring stations within 25 km and their daily mean PM2.5, PM10, NO2, O3, SO2 and CO with units. Use it for ground-station pollution data for a place and period.
POST /api/v1/get_air_quality · Pack: Earth & environment · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
latitude | number | yes | Latitude in decimal degrees. |
longitude | number | yes | Longitude in decimal degrees. |
radius_km | number | no | Search radius in km (default and maximum 25). |
pollutants | "pm25" | "pm10" | "no2" | "o3" | "so2" | "co"[] | no | Pollutants to return. Default: all of pm25, pm10, no2, o3, so2, co. |
start | string | no | First day, YYYY-MM-DD. Default: 7 days before end. |
end | string | no | Last day, YYYY-MM-DD. Default: today. |
lookup_astro_object
Resolve the name of a star, galaxy, nebula or other object outside the Solar System in SIMBAD. Returns the main identifier, object type, ICRS coordinates in degrees, parallax, proper motion, radial velocity, spectral type, V magnitude and other identifiers.
POST /api/v1/lookup_astro_object · Pack: Astronomy · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
name | string | yes | Object name or catalogue identifier, e.g. M31, Betelgeuse, HD 209458, TRAPPIST-1. |
search_exoplanets
Search confirmed exoplanets in the NASA Exoplanet Archive (composite parameters, one row per planet) by host star, name, discovery method, distance, radius or discovery year. Returns period, radius, mass, equilibrium temperature, insolation, distance and the discovery reference. The habitable-zone filter is approximate.
POST /api/v1/search_exoplanets · Pack: Astronomy · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
host_star | string | no | Exact host star name, e.g. TRAPPIST-1 or Kepler-186. |
planet_name | string | no | Planet name or part of it, e.g. "Proxima Cen b". |
discovery_method | string | no | Discovery method, e.g. Transit, Radial Velocity, Imaging, Microlensing, Transit Timing Variations, Astrometry. |
max_distance_pc | number | no | Maximum distance from the Sun in parsecs. |
min_radius_earth | number | no | Minimum planet radius in Earth radii. |
max_radius_earth | number | no | Maximum planet radius in Earth radii. |
in_habitable_zone | boolean | no | Approximate habitable zone only: insolation between 0.25 and 1.7 times what Earth receives. |
discovered_after | integer | no | Only planets discovered after this year. |
limit | integer | no | Planets to return (default 25). |
query_gaia
List Gaia DR3 sources within a radius of a sky position (cone search), brightest first. Returns position, parallax, proper motion, G/BP/RP magnitudes, radial velocity and effective temperature for each source. Use lookup_astro_object first to get the coordinates of a named object.
POST /api/v1/query_gaia · Pack: Astronomy · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
ra | number | yes | Right ascension of the centre in degrees (ICRS). |
dec | number | yes | Declination of the centre in degrees (ICRS). |
radius_deg | number | yes | Search radius in degrees (maximum 1.0). |
max_g_mag | number | no | Only sources at least this bright in the G band. |
limit | integer | no | Sources to return (default 50). |
search_archives
Search digitised primary sources: historical US newspaper pages (Chronicling America, full OCR text), photographs, maps and manuscripts from the Library of Congress, and cultural heritage items from Europeana. Returns title, date, place, rights statement, thumbnail, item link and a text snippet for each item.
POST /api/v1/search_archives · Pack: Humanities & math · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Keywords, e.g. "influenza Chicago". For newspapers every word must appear on the page. |
type | "newspaper" | "image" | "manuscript" | "map" | "any" | no | Kind of material (default any). |
date_from | integer | no | Earliest year, e.g. 1918. |
date_to | integer | no | Latest year, e.g. 1918. |
sources | "loc" | "europeana"[] | no | Limit to these sources: loc (Library of Congress), europeana. Default: both. |
limit | integer | no | Items to return (default 10). |
lookup_integer_sequence
Identify or look up an integer sequence in the OEIS from its first terms ("1,1,2,3,5,8"), an A-number (A000045) or keywords. Returns the A-number, name, first terms, formulas and keywords. Use it to recognise a sequence from computed terms or to find its formula and references.
POST /api/v1/lookup_integer_sequence · Pack: Humanities & math · 1 credit per successful call
| Argument | Type | Required | Description |
|---|---|---|---|
query | string | yes | Comma-separated terms such as "1,1,2,3,5,8", an A-number such as A000045, or keywords. |
limit | integer | no | Sequences to return (default 5). |