Programmatic Dataset Submission

Submit datasets directly from automated pipelines — Snakemake, Nextflow, Jupyter notebooks, or any script — using the Python SDK, the REST API, or the stomics submit CLI command. All methods require an API key.

1. Install the SDK

Requires Python 3.9+.

pip install "stomics-py"
# Ensure your API key is available:
export STOMICS_API_KEY="sk-your-key-here"

2. Run the submission workflow

The upload_file method uses a presigned S3 PUT URL — the file goes directly to storage without passing through the server.

from stomics import StomicsClient

client = StomicsClient(api_key="sk-...")

# 1. Create a draft dataset
ds = client.create_dataset(
    title="Spatial Atlas of the Mouse Brain Cortex",
    abstract="High-resolution 10x Visium profiling of...",
    organism="Mus musculus",
    tissue="brain cortex",
    technology="10x Visium",
    embargo_days=365,           # optional — set public release date
)
print(ds.accession)             # → STD0042

# 2. Add samples (optional bulk form)
client.add_sample(ds.accession, title="Section 1", section_id="A1")
# Or add many at once (up to 500 per call):
client.add_samples(ds.accession, [
    {"title": "Section 2", "section_id": "A2"},
    {"title": "Section 3", "section_id": "A3"},
])

# 3. Upload files — streams directly to S3, no server relay
client.upload_file(ds.accession, "matrix.h5ad",          file_type="expression_matrix")
client.upload_file(ds.accession, "tissue_positions.csv",  file_type="spatial_coordinates")
client.upload_file(ds.accession, "tissue_hires_image.tif", file_type="tissue_image")

# 4. Submit for curator review
updated = client.submit(ds.accession)
print(updated.status)           # → under_review

Method reference

Method	Description
`client.create_dataset(title, abstract, organism, tissue, technology, …)`	Create a draft dataset, returns Dataset with accession
`client.add_sample(accession, title, description, section_id)`	Add a single sample
`client.add_samples(accession, [{title, …}, …])`	Bulk-insert up to 500 samples in one request
`client.upload_file(accession, local_path, file_type)`	Upload a file via presigned S3 PUT URL
`client.submit(accession)`	Submit the dataset for curator review

Related resources

Create an API key — required for programmatic access
SDK Quick Start — read API documentation and data loading workflows
API Reference — full OpenAPI documentation