API reference¶
Malva exposes an HTTP API on the same origin as the web interface,
https://malva.mdc-berlin.de. You can call it directly with any HTTP client,
or use the malva_client Python package, which wraps this
API and returns pandas-friendly objects.
The API covers everything the web interface can do:
- Expression search. Submit a search for genes, FASTA sequences or a natural-language query, poll its status, then download results, cell IDs and expression matrices.
- Coverage search. Search a genomic region or a pasted DNA sequence and retrieve per-group coverage tracks.
- Cell groups. Create, share and analyse groups with marker genes and differential expression.
- Jobs. List your search history, inspect and manage individual jobs.
- Metadata. Browse samples, studies, datasets, filter values, ontologies and database statistics.
Base URL¶
All endpoints live under the same origin as the web interface:
Paths that start with /api/ are the explorer's native API. The /search/
and /samples/api/ paths are compatibility routes that the malva_client
package uses.
Two ways to use the API¶
| Approach | Best for | Reference |
|---|---|---|
| HTTP API directly | Custom integrations, scripts in any language | This section |
malva_client Python package |
Data analysis in Python, notebooks | Python client |
Both approaches use the same authentication, quota and search backend, and both count against your daily search quota.
Authentication¶
Most endpoints require a signed-in user. You authenticate either with an API token sent as a Bearer header (recommended for scripts) or with a browser session cookie. See Authentication for how to create a token and send it.
Responses¶
Responses are JSON unless the endpoint description says otherwise. A few
compatibility endpoints stream binary payloads in the
application/x-msgpack format for performance; they decode to the same
structure as their JSON equivalents.
Errors¶
Errors use the standard HTTP status codes and a JSON body with an error
field where relevant:
| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Invalid request, for example a malformed query or region |
| 401 | Authentication required or the token is invalid |
| 404 | Not found, for example an unknown job or share token |
| 410 | Expired, for example a result that has been removed |
| 429 | Daily search quota exceeded, body contains quota_exceeded |
| 502 | An upstream service (search or metadata) is unavailable |
| 503 | An upstream service is still starting up or the app is in maintenance |
Quotas¶
Every submitted search consumes one unit of your daily quota, regardless of
how many genes or sequences the query contains. The response of
POST /api/expression/submit includes your remaining quota. See
Quotas and limits for the numbers.