API documentation

The OpenMPRA API provides read-only access to study and experiment metadata, processed tables, and retained raw files. No account or API key is required. Requests use HTTPS and GET; browser requests from other origins are supported.

Base URL

https://mpra.johnomeara.com/api/v1/

API information OpenAPI 3.1 specification

Endpoints

All paths below are relative to the base URL. Replace {study} and {experiment} with database IDs, for example S01W08WW3 and E0BH5W6AR. Download links in JSON responses are relative to the site origin.

GET path	Response
`/`	API information and database counts
`/studies`	Search and paginate study summaries
`/experiments`	Search and paginate experiment metadata
`/studies/{study}`	Study metadata, experiments, and raw-file names
`/studies/{study}/experiments/{experiment}`	Parent study and complete experiment metadata
`/studies/{study}/experiments/{experiment}/rows`	Read and filter a processed table, 50 rows at a time
`/studies/{study}/experiments/{experiment}/table.csv`	Download the complete processed CSV, with unchanged values
`/studies/{study}/raw-files`	List retained raw files and their download URLs
`/studies/{study}/raw`	Download one retained raw file using the file query parameter
`/studies/{study}/raw.zip`	Download all retained raw files as a ZIP with nested folders preserved

Search studies and experiments

/studies returns study summaries, including matching experiment IDs. /experiments returns complete experiment metadata, including column definitions. Both accept these parameters:

Parameter	Meaning
q	Case-insensitive terms separated by whitespace. All terms must match publication or experiment metadata. This does not search table cells.
assay, organism, genome, focus, biosample	Exact metadata values. For example, organism=NCBITaxon:9606 or focus=Variant-focused. Filters must match within the same experiment.
year	Publication year, such as 2025.
page	Starts at 1. Maximum 100,000.
limit	Records per page: default 25, maximum 100.
sort	newest (default), oldest, title, or experiments (most matching experiments first). Experiment results follow their parent study’s ordering.

Supply each parameter once. Text query values accept at most 200 characters. List responses contain data and pagination with page, limit, total, pages, and has_more. The database can change between requests; for long analyses, save the returned metadata and IDs locally.

curl --get 'https://mpra.johnomeara.com/api/v1/studies' --data-urlencode 'q=keratinocyte' --data-urlencode 'organism=NCBITaxon:9606' --data-urlencode 'limit=25'

Python example: paginate experiments using the standard library

import json
from urllib.parse import urlencode
from urllib.request import urlopen

base = "https://mpra.johnomeara.com/api/v1"
page = 1
while True:
    params = urlencode({"organism": "NCBITaxon:9606", "page": page, "limit": 100})
    with urlopen(f"{base}/experiments?{params}") as response:
        result = json.load(response)
    for experiment in result["data"]:
        print(experiment["study_id"], experiment["experiment_id"])
    if not result["pagination"]["has_more"]:
        break
    page += 1

Processed table rows

Request /studies/{study}/experiments/{experiment}/rows for up to 50 matching rows. Responses contain columns, rows, page, pageSize, and hasMore. Cell values remain strings, including numeric-looking values and empty strings. Row pages are numbered within the matching result set.

Parameter	Meaning
page	Starts at 1; maximum 10,000. Page size is fixed at 50.
q	Case-insensitive substring in any cell.
column	Exact header name from this experiment’s table.
op	contains (default), eq (case-sensitive text equality), lte (numeric ≤), or gte (numeric ≥).
value	Column filter value. Both column and a nonempty value are required. Numeric comparisons exclude empty and nonnumeric cells.

GET /studies/S01W08WW3/experiments/E0BH5W6AR/rows?column=d0_allelic_fdr&op=lte&value=0.05

Tables are not standardized across experiments. Read column_descriptions, quality_control_description, and agent_comments before interpreting data. Scans stop after 60 seconds and at most four can run simultaneously per server process. Use the complete CSV for large local analyses.

Downloads

The table.csv endpoint downloads the complete processed experiment table. It preserves file bytes and does not apply row filters. Raw source inputs are separate: raw-files lists available filenames, raw?file=… downloads one file, and raw.zip downloads all retained raw files for a study. URL-encode filenames, including spaces and nested folders.

curl -fL 'https://mpra.johnomeara.com/api/v1/studies/S01W08WW3/experiments/E0BH5W6AR/table.csv' -o processed.csv
curl -fL 'https://mpra.johnomeara.com/api/v1/studies/S01W08WW3/raw.zip' -o raw-data.zip

ZIP entries use {study}/raw_data/… and retain subfolders. Source licenses apply. Downloads stream through OpenMPRA; clients never need access to the internal file server. Study full text is not served by this API. Downloads do not support byte-range resume. If a connection fails mid-download, discard the partial file and retry.

Errors and usage limits

Errors before a download begins are JSON with statusCode and statusMessage. Typical statuses: 400 invalid parameters, 404 missing record/file, 405 unsupported method, 429 concurrent request limit, 502 source unavailable or invalid, 503 index unavailable, and 504 table scan timeout. Unexpected server failures return 500.

Retry transient errors with exponential backoff. Limits per server process are four table scans, eight individual downloads, and two raw ZIP downloads at a time. Source requests and whole ZIP downloads have a 10-minute time limit. Avoid repeatedly downloading unchanged files; save local copies for analysis.

Metadata is indexed periodically while table and raw-file bytes are read when requested. These are not transactional snapshots. Unknown metadata values are null; empty CSV cells are empty strings. GET, HEAD, and OPTIONS are supported. No public write endpoints are provided.