Skip to content

API Quickstart

The MaveDB REST API provides programmatic access to all public data in MaveDB. You can use it to search for datasets, download scores, and retrieve variant mappings without using the web interface.

API documentation

The full interactive API documentation is available at api.mavedb.org/docs and includes detailed information on all endpoints, request/response formats, and example requests in multiple programming languages.

Base URL

All API endpoints are available at:

https://api.mavedb.org/api/v1/

Authentication

Reading public data does not require authentication. You can fetch any published dataset without an API key.

For write operations (creating experiments, uploading scores) or accessing your private datasets, you need an API key. Generate one from your Profile settings page after logging in. See User Accounts for more details.

Keep your API key secret

Your API key grants full access to your MaveDB account. Do not commit it to version control, share it publicly, or include it in client-side code. Use environment variables or a secrets manager to store it securely.

Include your key in requests using the x-api-key header:

import os
import requests

response = requests.get(
    "https://api.mavedb.org/api/v1/users/me",
    headers={"x-api-key": os.environ["MAVEDB_API_KEY"]}
)

library(httr)

response <- GET(
  "https://api.mavedb.org/api/v1/users/me",
  add_headers(`x-api-key` = Sys.getenv("MAVEDB_API_KEY"))
)

curl -H "x-api-key: $MAVEDB_API_KEY" https://api.mavedb.org/api/v1/users/me

Common Tasks

Fetch a score set by URN

Each score set in MaveDB is identified by a unique accession number (URN).

import requests

response = requests.get("https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1")
score_set = response.json()

print(score_set["title"])
print(f"Variants: {score_set['numVariants']}")

library(httr)
library(jsonlite)

response <- GET("https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1")
score_set <- content(response, as = "parsed")

cat(score_set$title, "\n")
cat("Variants:", score_set$numVariants, "\n")

curl https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1

Download variant scores as CSV

import requests

response = requests.get("https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1/scores")

with open("scores.csv", "w") as f:
    f.write(response.text)

library(httr)

response <- GET("https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1/scores")
writeLines(content(response, as = "text"), "scores.csv")

curl -o scores.csv https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1/scores

Search for score sets

The search endpoint uses POST with a JSON body:

import requests

response = requests.post(
    "https://api.mavedb.org/api/v1/score-sets/search",
    json={"text": "BRCA1"}
)
results = response.json()

for score_set in results:
    print(f"{score_set['urn']}: {score_set['title']}")

library(httr)
library(jsonlite)

response <- POST(
  "https://api.mavedb.org/api/v1/score-sets/search",
  body = list(text = "BRCA1"),
  encode = "json"
)
results <- content(response, as = "parsed")

for (score_set in results) {
  cat(score_set$urn, ": ", score_set$title, "\n")
}

curl -X POST https://api.mavedb.org/api/v1/score-sets/search \
  -H "Content-Type: application/json" \
  -d '{"text": "BRCA1"}'

Download mapped variants (VRS format)

For datasets with human targets, mapped variants are available in GA4GH VRS format:

import requests

response = requests.get(
    "https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1/mapped-variants"
)

with open("mapped_variants.json", "w") as f:
    f.write(response.text)

library(httr)

response <- GET("https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1/mapped-variants")
writeLines(content(response, as = "text"), "mapped_variants.json")

curl -o mapped_variants.json \
  https://api.mavedb.org/api/v1/score-sets/urn:mavedb:00000003-a-1/mapped-variants

List score sets in an experiment

import requests

response = requests.get("https://api.mavedb.org/api/v1/experiments/urn:mavedb:00000003-a/score-sets")
score_sets = response.json()

for ss in score_sets:
    print(f"{ss['urn']}: {ss['title']}")

library(httr)
library(jsonlite)

response <- GET("https://api.mavedb.org/api/v1/experiments/urn:mavedb:00000003-a/score-sets")
score_sets <- content(response, as = "parsed")

for (ss in score_sets) {
  cat(ss$urn, ": ", ss$title, "\n")
}

curl https://api.mavedb.org/api/v1/experiments/urn:mavedb:00000003-a/score-sets

Pagination

List and search endpoints support pagination using limit and offset query parameters:

import requests

response = requests.post(
    "https://api.mavedb.org/api/v1/score-sets/search",
    json={"text": "BRCA1", "limit": 10, "offset": 0}
)

library(httr)

response <- POST(
  "https://api.mavedb.org/api/v1/score-sets/search",
  body = list(text = "BRCA1", limit = 10, offset = 0),
  encode = "json"
)

curl -X POST https://api.mavedb.org/api/v1/score-sets/search \
  -H "Content-Type: application/json" \
  -d '{"text": "BRCA1", "limit": 10, "offset": 0}'

Rate Limits

The MaveDB API does not currently enforce rate limits. However, please be considerate with API usage. For downloading many datasets at once, consider using the bulk download archive instead.

Next Steps