Metadata and data

The metadata endpoints let you browse the samples, studies, datasets and ontologies behind the database, and read the database statistics. Most of these endpoints are public, because the metadata is what the results table groups on.

Endpoints

Method	Path	Auth	Purpose
GET	/api/metadata/ontology	Public	Ontology JSON for the app
GET	/api/metadata/cell-types	Public	List of cell types
GET	/api/metadata/available-filters	Public	Metadata columns you can filter on
POST	/api/metadata/filter-values/<column>	Public	Values for one filter column
POST	/api/metadata/groups	Public	Sample groups by metadata columns
POST	/api/metadata/publications/search	Public	Search publications
POST	/api/metadata/external-metadata	Public	Enrich a DOI with external sources
GET	/api/ontology/fields	Public	Ontology-backed columns
GET	/api/ontology/<field>/<ontology_id>	Public	Full node map of an ontology
GET	/api/filter-presets	Public	Your saved filter presets
POST	/api/filter-presets	Required	Save a filter preset
DELETE	/api/filter-presets/<preset_id>	Required	Delete a preset
GET	/api/stats	Public	Database statistics
GET	/api/stats/terms	Public	Word-cloud term lists
GET	/api/status	Public	Health of the search services
GET	/api/version	Public	Application version

Browse samples

The compatibility routes under /samples/api/ proxy the metadata service and are used by malva_client:

Method	Path	Purpose
GET	/samples/api/search	Search samples
GET	/samples/api/studies	List studies
GET	/samples/api/overview	Overview counts
GET	/samples/api/filters	Filter columns and values
GET	/samples/api/filters/<column>/values	Values for one column
GET	/samples/api/datasets/hierarchy	Dataset hierarchy
GET	/samples/api/datasets/<dataset_id>/studies	Studies in a dataset
GET	/samples/api/datasets/<dataset_id>/studies/<study_name>/samples	Samples in a study
GET	/samples/api/sample/<sample_uuid>	Full metadata for one sample

Sample downloads

The metadata service can serve the raw files behind a sample:

Method	Path	Purpose
GET	/api/samples/<sample_uuid>/download	Create a download token and URL
GET	/api/download/<token>	Stream the file through the explorer
GET	/api/samples/<sample_uuid>/download/info	Download availability

The download response contains {download_url, download_token, filename, file_size, expires_at, expires_in_seconds}. Downloads are time-limited, so start the stream before the token expires.

Filter values

curl -X POST https://malva.mdc-berlin.de/api/metadata/filter-values/disease \
  -H "Content-Type: application/json" \
  -d '{"search": "covid", "limit": 20}'

Returns {values, total}. The POST /api/metadata/groups endpoint returns sample groups for a set of metadata columns, the same data that powers the Browse panel in the Expression Explorer.

Ontologies

• GET /api/ontology/fields lists the ontology-backed metadata columns with their ontologies and mapping strategies.
• GET /api/ontology/<field>/<ontology_id> returns the full node map {roots, nodes, max_depth} of an ontology, for example a MONDO disease or UBERON organ subtree.

Filter presets

Filter presets are saved per user:

curl -X POST https://malva.mdc-berlin.de/api/filter-presets \
  -H "Authorization: Bearer malva_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Lung COVID", "filters": {"disease": ["COVID-19"]}, "numFilters": 1}'

Anonymous callers receive an empty list from GET /api/filter-presets, and a 401 from the mutating endpoints.

Statistics

• GET /api/stats returns {total_cells, total_samples, total_datasets, unique_cell_types, unique_diseases, total_organs, total_organisms, total_laboratories, raw_data_tb}.
• GET /api/stats/terms returns {cell_types, diseases, organs} as term lists with counts for the word clouds.
• GET /api/status returns the health of the search and metadata services.
• GET /api/version returns {version, is_latest}. The version tracks the application release; the documentation is versioned in sync with it.