API Documentation

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

Authentication

Reading public datasets needs no key. To submit data, or to download controlled-access files you have been granted, 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. Every request made with a key reports its quota in RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. An invalid or expired key is rejected with 401.

AI agents (MCP)

Stomics runs a remote Model Context Protocol server, so assistants such as Claude can search datasets, read their metadata and fetch download links directly. It needs no authentication and every tool is read-only. Add this URL as a custom connector:

https://stomics.io/api/v1/mcp

In Claude Code: claude mcp add --transport http stomics https://stomics.io/api/v1/mcp. A summary for agents is at /llms.txt.

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, 2],  # repeat the parameter for several 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
Technologies: GET /api/v1/vocabulary/technologies
Ontology terms: GET /api/v1/vocabulary/terms?kind=organism
MCP server: POST /api/v1/mcp

Full OpenAPI schema at /api/v1/openapi.json, browsable at /api/v1/docs.