# BioSamples API > BioSamples as an API, powered by EMBL-EBI — the database that stores and links the metadata of biological samples, the physical specimens behind biological experiments. A sample in BioSamples carries a stable accession (such as SAMEA3231268) and a rich set of characteristics — organism, tissue or organism part, cell type, sex, disease, developmental stage, strain and any submitter-provided attributes — and is referenced by other EBI archives including the European Nucleotide Archive (ENA), ArrayExpress and PRIDE. /v1/search?q=liver searches samples by free text and returns each match's accession, name, organism and release date. /v1/sample?id=SAMEA3231268 returns a sample's metadata — its accession, name, NCBI taxon id, organism, release and update dates, the number of relationships to other samples, and its characteristics flattened to a clean key→value map. Accessions look like SAMEA…, SAMN… or SAMD…; get one from the search endpoint. Ideal for life-science data integration, sample tracking, metadata harmonisation and linking sequencing or expression data back to its source specimen. Data from EMBL-EBI BioSamples (public). This is a biological-sample metadata registry — distinct from study (BioStudies), sequence (ENA), variant (ClinVar) and structure databases. ## Authentication All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys. ```bash curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/biosamples-api/..." ``` ## Pricing - **Free** (Free) — 2,050 calls/Mo, 2 req/s - **Starter** ($6/Mo) — 46,000 calls/Mo, 5 req/s - **Pro** ($19/Mo) — 211,000 calls/Mo, 12 req/s - **Mega** ($51/Mo) — 772,000 calls/Mo, 35 req/s ## Endpoints ### Samples #### `GET /v1/sample` — A sample metadata **Parameters:** - `id` (query, required, string) — BioSamples accession (from /v1/search), e.g. SAMEA3231268 Example: `SAMEA3231268` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/biosamples-api/v1/sample?id=SAMEA3231268" ``` **Response:** ```json { "data": { "sample": { "url": "https://www.ebi.ac.uk/biosamples/samples/SAMEA3231268", "name": "SPN_E_2_TB_E_1-sc-2216731", "domain": "Webin-2", "tax_id": 1427524, "update": "2024-02-06", "release": "2015-06-30", "organism": "mixed sample", "accession": "SAMEA3231268", "relationships": 0, "characteristics": { "strain": "mixed sample", "organism": "mixed sample", "External Id": "SAMEA3231268", "INSDC status": "public", "Submitter Id": "SPN_E_2_TB_E_1-sc-2216731", "ENA-CHECKLIST": "ERC000011", "SRA accession": "ERS652502", "ENA-LAST-UPDATE": "2018-03-09T12:37:01Z", "scientific_name": "mixed sample", "ENA-FIRST-PUBLIC": "2015-06-30T09:40:43Z", "INSDC center name": "SC", "INSDC last update": "2018-03-09T12:37:01Z", "INSDC first public": "2015-06-30T09:40:43Z", "ArrayExpress-Species": "mixed sample", "ArrayExpress-StrainOrLine": "mixed sample" } } }, "meta": { "timestamp": "2026-06-01T16:23:15.347Z", "request_id": "b4a4479e-32fb-43cb-9205-dfa81d13f1d6" }, "status": "ok", "message": "Sample retrieved", "success": true } ``` #### `GET /v1/search` — Search biological samples **Parameters:** - `q` (query, required, string) — Search text, e.g. liver Example: `liver` - `limit` (query, optional, string) — Max results (1-100) **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/biosamples-api/v1/search?q=liver" ``` **Response:** ```json { "data": { "count": 20, "query": "liver", "samples": [ { "url": "https://www.ebi.ac.uk/biosamples/samples/SAMD00004696", "name": "SAMD00004696", "release": "2014-03-28", "organism": "Mus musculus", "accession": "SAMD00004696" }, { "url": "https://www.ebi.ac.uk/biosamples/samples/SAMD00004746", "name": "SAMD00004746", "release": "2014-03-28", "organism": "Mus musculus", "accession": "SAMD00004746" }, { "url": "https://www.ebi.ac.uk/biosamples/samples/SAMD00004760", "name": "SAMD00004760", "release": "2014-03-28", "organism": "Mus musculus", "accession": "SAMD00004760" }, { "url": "https://www.ebi.ac.uk/biosamples/samples/SAMD00004776", "name": "SAMD00004776", "release": "2014-03-28", "organism": "Mus musculus", "accession": "SAMD00004776" }, { "url": "https://www.ebi.ac.uk/biosamples/samples/SAMD00004811", "name": "SAMD00004811", "release": "2014-03-28", "organism": "Homo sapiens", "accession": "SAMD00004811" }, { …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Usage notes **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/biosamples-api/v1/meta" ``` **Response:** ```json { "data": { "note": "BioSamples is EMBL-EBI's registry of metadata about biological samples (specimens) — the physical material behind experiments, referenced by archives such as ENA, ArrayExpress and PRIDE. /v1/search?q=liver = search samples by free text, returning each sample's accession (e.g. SAMEA3231268), name, organism and release date; /v1/sample?id=SAMEA3231268 = a sample's metadata — accession, name, NCBI taxon id, organism, release and update dates, number of relationships, and its characteristics (organism, organism part/tissue, cell type, sex, disease, strain and any submitter-provided attributes, flattened to key→value). Accessions look like SAMEA…, SAMN… or SAMD…; get one from /v1/search. Data from EMBL-EBI BioSamples (public). This is a biological-sample metadata registry — distinct from study (BioStudies), sequence (ENA), variant and structure databases.", "source": "EMBL-EBI BioSamples (ebi.ac.uk/biosamples)", "endpoints": [ "/v1/search", "/v1/sample", "/v1/meta" ] }, "meta": { "timestamp": "2026-06-01T16:23:16.206Z", "request_id": "2c861ff9-d9ef-4646-8fdc-069d9c89773b" }, "status": "ok", "message": "Meta retrieved", "success": true } ``` --- Marketplace page: https://www.oanor.com/api/biosamples-api OpenAPI spec: https://www.oanor.com/api/biosamples-api/openapi.json