API Documentation

Access the Stomics REST API programmatically using an API key. Authentication works on all endpoints that accept browser login.

Authentication

Generate an API key from your account settings. Pass it as a Bearer token in every request:

Authorization: Bearer sk-your-api-key-here

Rate limit: 1,000 requests per hour per key. Exceeded requests receive 429 Too Many Requests with a Retry-After header.

1. List datasets with filters

Search and filter the dataset catalog. All query parameters are optional.

import requests

API_KEY = "sk-your-api-key-here"
BASE_URL = "https://stomics.io"

headers = {"Authorization": f"Bearer {API_KEY}"}

# List published datasets with optional filters
response = requests.get(
    f"{BASE_URL}/api/v1/datasets",
    headers=headers,
    params={
        "q": "brain",              # free-text search
        "technology_ids": "1",     # comma-separated IDs
        "sort_by": "download_count",
        "sort_order": "desc",
        "page": 1,
        "per_page": 20,
    },
)
response.raise_for_status()

data = response.json()
print(f"Found {data['total']} datasets")
for dataset in data["items"]:
    print(f"  {dataset['accession']}  {dataset['title']}")

2. Get a dataset's file list

Retrieve the files available for download for a given dataset accession.

import requests

API_KEY = "sk-your-api-key-here"
BASE_URL = "https://stomics.io"

headers = {"Authorization": f"Bearer {API_KEY}"}

accession = "STD0001"

# Get all files for a dataset
response = requests.get(
    f"{BASE_URL}/api/v1/datasets/{accession}/files",
    headers=headers,
)
response.raise_for_status()

files = response.json()
for f in files:
    size_mb = (f["size_bytes"] or 0) / 1_000_000
    print(f"  [{f['file_type']:25s}]  {f['filename']}  ({size_mb:.1f} MB)")

3. Download a file via pre-signed URL

Request a short-lived pre-signed S3 URL and stream the file to disk. Pre-signed URLs are valid for 1 hour and do not require authentication to use.

import requests

API_KEY = "sk-your-api-key-here"
BASE_URL = "https://stomics.io"

headers = {"Authorization": f"Bearer {API_KEY}"}

accession = "STD0001"
file_id = 42          # from the files list above

# Get a pre-signed download URL (valid for 1 hour)
response = requests.get(
    f"{BASE_URL}/api/v1/datasets/{accession}/files/{file_id}/download",
    headers=headers,
)
response.raise_for_status()
presigned_url = response.json()["url"]

# Stream the file to disk (no auth header needed for pre-signed URLs)
with requests.get(presigned_url, stream=True) as r:
    r.raise_for_status()
    with open("matrix.h5ad", "wb") as fh:
        for chunk in r.iter_content(chunk_size=8192):
            fh.write(chunk)

print("Downloaded matrix.h5ad")

Quick reference

Base URL: https://stomics.io
List datasets: GET /api/v1/datasets
Dataset detail: GET /api/v1/datasets/{accession}
Dataset files: GET /api/v1/datasets/{accession}/files
Download URL: GET /api/v1/datasets/{accession}/files/{id}/download
Expression data: GET /api/v1/datasets/{accession}/expression?gene=…

Full OpenAPI schema available at /api/v1/openapi.json.