{"openapi": "3.0.2", "info": {"title": "HoloFood Data Portal API", "version": "1.0.0", "description": "The API to browse [HoloFood](https://www.holofood.eu) samples and metadata, and navigate to datasets stored in public archives. \n\n #### Useful links: \n- [Documentation](https://ebi-metagenomics.github.io/holofood-database/)\n- [HoloFood Data Portal home](/)\n- [HoloFood Project Website](https://www.holofood.eu)\n- [Helpdesk](https://www.ebi.ac.uk/contact)\n- [TSV Export endpoints](/export/docs)"}, "paths": {"/api/samples/{sample_accession}": {"get": {"operationId": "holofood_api_get_sample", "summary": "Fetch a single Sample from the HoloFood database.", "parameters": [{"in": "path", "name": "sample_accession", "schema": {"title": "Sample Accession", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SampleSchema"}}}}}, "description": "Retrieve a single Sample by its ENA accession, including all structured metadata available. ", "tags": ["Samples"]}}, "/api/samples": {"get": {"operationId": "holofood_api_list_samples", "summary": "Fetch a list of Samples.", "parameters": [{"in": "query", "name": "system", "schema": {"title": "System", "description": "An enumeration.", "enum": ["salmon", "chicken"]}, "required": false, "description": "An enumeration."}, {"in": "query", "name": "accession", "schema": {"title": "Accession", "type": "string"}, "required": false}, {"in": "query", "name": "title", "schema": {"title": "Title", "type": "string"}, "required": false}, {"in": "query", "name": "sample_type", "schema": {"title": "SampleType", "description": "An enumeration.", "enum": ["metagenomic_assembly", "metagenomic_amplicon", "metabolomic", "metabolomic_targeted", "histological", "host_genomic", "iodine", "heavy_metals", "fatty_acids", "transcriptomic", "metatranscriptomic", "inflammatory_markers"]}, "required": false, "description": "An enumeration."}, {"in": "query", "name": "animal_accession", "schema": {"title": "Animal Accession", "type": "string"}, "required": false}, {"in": "query", "name": "require_metadata_marker", "schema": {"title": "Require Metadata Marker", "type": "string"}, "required": false}, {"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedSampleSlimSchema"}}}}}, "description": "Long lists will be paginated, so use the `page=` query parameter to get more pages. Several filters are available, which mostly perform case-insensitive containment lookups. Sample metadata are *not* returned for each item. Use the `/samples/{sample_accession}` endpoint to retrieve those. Sample metadata *can* be filtered for with `require_metadata_marker=`: this finds samples where the named metadata marker is present and none of `['0', 'false', 'unknown', 'n/a', 'null]`. Use `/sample_metadata_markers` to find the exact marker name of interest.", "tags": ["Samples"]}}, "/api/animals/{animal_accession}": {"get": {"operationId": "holofood_api_get_animal", "summary": "Fetch a single Animal (a host-level BioSample) from the HoloFood database.", "parameters": [{"in": "path", "name": "animal_accession", "schema": {"title": "Animal Accession", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AnimalSchema"}}}}}, "description": "Retrieve a single Animal by its BioSamples accession, including all structured metadata available. ", "tags": ["Samples"]}}, "/api/animals": {"get": {"operationId": "holofood_api_list_animals", "summary": "Fetch a list of Animals (host-level BioSamples).", "parameters": [{"in": "query", "name": "system", "schema": {"title": "System", "description": "An enumeration.", "enum": ["salmon", "chicken"]}, "required": false, "description": "An enumeration."}, {"in": "query", "name": "accession", "schema": {"title": "Accession", "type": "string"}, "required": false}, {"in": "query", "name": "require_metadata_marker", "schema": {"title": "Require Metadata Marker", "type": "string"}, "required": false}, {"in": "query", "name": "require_sample_type", "schema": {"title": "SampleType", "description": "An enumeration.", "enum": ["metagenomic_assembly", "metagenomic_amplicon", "metabolomic", "metabolomic_targeted", "histological", "host_genomic", "iodine", "heavy_metals", "fatty_acids", "transcriptomic", "metatranscriptomic", "inflammatory_markers"]}, "required": false, "description": "An enumeration."}, {"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedAnimalSlimSchema"}}}}}, "description": "Long lists will be paginated, so use the `page=` query parameter to get more pages. Several filters are available, which mostly perform case-insensitive containment lookups. Animal metadata are *not* returned for each item. Use the `/animals/{animal_accession}` endpoint to retrieve those. Animal metadata *can* be filtered for with `require_metadata_marker=`: this finds animals where the named metadata marker is present and none of `['0', 'false', 'unknown', 'n/a', 'null]`. The `require_sample_type=` filter finds only animals where at least one derived sample of the specified type exists. Use `/sample_metadata_markers` to find the exact marker name of interest.", "tags": ["Samples"]}}, "/api/sample_metadata_markers": {"get": {"operationId": "holofood_api_list_sample_metadata_markers", "summary": "Fetch a list of structured metadata markers (i.e. keys).", "parameters": [{"in": "query", "name": "name", "schema": {"title": "Name", "type": "string"}, "required": false}, {"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedSampleMetadataMarkerSchema"}}}}}, "description": "Each marker is present in the metadata of at least one sample. Not every sample will have every metadata marker. Long lists will be paginated, so use the `page=` query parameter to get more pages. Use `name=` to search for a marker by name (case insensitive partial matches). ", "tags": ["Samples"]}}, "/api/analysis-summaries": {"get": {"operationId": "holofood_api_list_analysis_summaries", "summary": "Fetch a list of Analysis Summary documents.", "parameters": [{"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedAnalysisSummarySchema"}}}}}, "description": "Analysis Summary documents are produced by HoloFood partners and collaborators. Each summary is tagged as involving 1 or more Samples or Catalogues. Typically these are aggregative or comparative analyses of the Samples. These are text and graphic documents. They are not intended for programmatic consumption, so a website URL is returned for each. ", "tags": ["Analysis Summaries"]}}, "/api/genome-catalogues": {"get": {"operationId": "holofood_api_list_genome_catalogues", "summary": "Fetch a list of Genome (MAG) Catalogues", "parameters": [{"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedGenomeCatalogueSchema"}}}}}, "description": "Genome Catalogues are lists of Metagenomic Assembled Genomes (MAGs)MAGs originating from HoloFood samples are organised into biome-specific catalogues.", "tags": ["Genomes"]}}, "/api/genome-catalogues/{catalogue_id}": {"get": {"operationId": "holofood_api_get_genome_catalogue", "summary": "Fetch a single Genome Catalogue", "parameters": [{"in": "path", "name": "catalogue_id", "schema": {"title": "Catalogue Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenomeCatalogueSchema"}}}}}, "description": "A Genome Catalogue is a list of Metagenomic Assembled Genomes (MAGs).MAGs originating from HoloFood samples are organised into biome-specific catalogues.To list the genomes for a catalogue, use `/genome-catalogues/{catalogue_id}/genomes`.", "tags": ["Genomes"]}}, "/api/genome-catalogues/{catalogue_id}/genomes": {"get": {"operationId": "holofood_api_list_genome_catalogue_genomes", "summary": "Fetch the list of Genomes within a Catalogue", "parameters": [{"in": "path", "name": "catalogue_id", "schema": {"title": "Catalogue Id", "type": "string"}, "required": true}, {"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedGenomeSchema"}}}}}, "description": "Genome Catalogues are lists of Metagenomic Assembled Genomes (MAGs).MAGs listed originate from HoloFood samples.Each MAG has also been clustered with MAGs from other projects.Each HoloFood MAG references the best representative of these clusters, in MGnify.", "tags": ["Genomes"]}}, "/api/genome-catalogues/{genome_catalogue_id}/genomes/{genome_id}": {"get": {"operationId": "holofood_api_get_genome", "summary": "Fetch the detail of a Genome", "parameters": [{"in": "path", "name": "genome_catalogue_id", "schema": {"title": "Genome Catalogue Id", "type": "string"}, "required": true}, {"in": "path", "name": "genome_id", "schema": {"title": "Genome Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenomeWithContainingSamplesSchema"}}}}}, "description": "A Genomes is a Metagenomic Assembled Genome (MAG).Each MAG originates from HoloFood samples.Each MAG has also been clustered with MAGs from other projects.Each HoloFood MAG references the best representative of these clusters, in MGnify.Each MAG has also been searched in all of the project samples, to find samples which contain the kmers of genome.", "tags": ["Genomes"]}}, "/api/viral-catalogues": {"get": {"operationId": "holofood_api_list_viral_catalogues", "summary": "Fetch a list of Viral (contig fragment) Catalogues", "parameters": [{"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedViralCatalogueSchema"}}}}}, "description": "Viral Catalogues are lists of Viral Sequences,detected in the assembly contigs of HoloFood samples from a specific biome.", "tags": ["Viruses"]}}, "/api/viral-catalogues/{catalogue_id}": {"get": {"operationId": "holofood_api_get_viral_catalogue", "summary": "Fetch a single Viral Catalogue", "parameters": [{"in": "path", "name": "catalogue_id", "schema": {"title": "Catalogue Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ViralCatalogueSchema"}}}}}, "description": "A Viral Catalogue is a list of Viral Sequences,detected in the assembly contigs of HoloFood samples from a specific biome.To list the viral sequences (\u201cfragments\u201d) for a catalogue, use `/viral-catalogues/{catalogue_id}/fragments`.", "tags": ["Viruses"]}}, "/api/viral-catalogues/{catalogue_id}/fragments": {"get": {"operationId": "holofood_api_list_viral_catalogue_fragments", "summary": "Fetch the list of viral fragments (sequences) from a Catalogue", "parameters": [{"in": "path", "name": "catalogue_id", "schema": {"title": "Catalogue Id", "type": "string"}, "required": true}, {"in": "query", "name": "page", "schema": {"title": "Page", "default": 1, "minimum": 1, "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PagedViralFragmentSchema"}}}}}, "description": "Viral fragments are sequences predicted to be viral, found in the assembly contigs of HoloFood samples.The Catalogue\u2019s viral fragments are all from the same biome.Viral sequences are clustered by sequence identity, at a species-level.Both cluster representatives and cluster members are included.", "tags": ["Viruses"]}}}, "components": {"schemas": {"SampleMetadataMarkerSchema": {"title": "SampleMetadataMarkerSchema", "type": "object", "properties": {"name": {"title": "Name", "maxLength": 100, "type": "string"}, "type": {"title": "Type", "maxLength": 100, "type": "string"}, "canonical_url": {"title": "Iri", "type": "string"}}, "required": ["name"]}, "SampleStructuredDatumSchema": {"title": "SampleStructuredDatumSchema", "type": "object", "properties": {"marker": {"$ref": "#/components/schemas/SampleMetadataMarkerSchema"}, "measurement": {"title": "Measurement", "maxLength": 300, "type": "string"}, "units": {"title": "Units", "maxLength": 100, "type": "string"}}, "required": ["marker", "measurement"]}, "RelatedAnalysisSummarySchema": {"title": "RelatedAnalysisSummarySchema", "type": "object", "properties": {"title": {"title": "Title", "maxLength": 200, "type": "string"}, "canonical_url": {"title": "Canonical Url", "type": "string"}}, "required": ["title", "canonical_url"]}, "SampleSchema": {"title": "SampleSchema", "type": "object", "properties": {"accession": {"title": "Accession", "maxLength": 15, "type": "string"}, "title": {"title": "Title", "maxLength": 200, "type": "string"}, "sample_type": {"title": "Sample Type", "maxLength": 20, "type": "string"}, "animal": {"title": "Animal", "type": "string"}, "canonical_url": {"title": "Canonical Url", "type": "string"}, "metagenomics_url": {"title": "Metagenomics Url", "type": "string"}, "metabolomics_url": {"title": "Metabolomics Url", "type": "string"}, "structured_metadata": {"title": "Structured Metadata", "type": "array", "items": {"$ref": "#/components/schemas/SampleStructuredDatumSchema"}}, "analysis_summaries": {"title": "Analysis Summaries", "type": "array", "items": {"$ref": "#/components/schemas/RelatedAnalysisSummarySchema"}}}, "required": ["title", "animal", "canonical_url", "metagenomics_url", "metabolomics_url", "structured_metadata", "analysis_summaries"]}, "SampleSlimSchema": {"title": "SampleSlimSchema", "type": "object", "properties": {"accession": {"title": "Accession", "maxLength": 15, "type": "string"}, "title": {"title": "Title", "maxLength": 200, "type": "string"}, "sample_type": {"title": "Sample Type", "maxLength": 20, "type": "string"}, "animal": {"title": "Animal", "type": "string"}, "canonical_url": {"title": "Canonical Url", "type": "string"}, "metagenomics_url": {"title": "Metagenomics Url", "type": "string"}, "metabolomics_url": {"title": "Metabolomics Url", "type": "string"}}, "required": ["title", "animal", "canonical_url", "metagenomics_url", "metabolomics_url"]}, "PagedSampleSlimSchema": {"title": "PagedSampleSlimSchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/SampleSlimSchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}, "AnimalStructuredDatumSchema": {"title": "AnimalStructuredDatumSchema", "type": "object", "properties": {"marker": {"$ref": "#/components/schemas/SampleMetadataMarkerSchema"}, "measurement": {"title": "Measurement", "maxLength": 300, "type": "string"}, "units": {"title": "Units", "maxLength": 100, "type": "string"}}, "required": ["marker", "measurement"]}, "AnimalSchema": {"title": "AnimalSchema", "type": "object", "properties": {"accession": {"title": "Accession", "maxLength": 15, "type": "string"}, "system": {"title": "System", "maxLength": 10, "type": "string"}, "canonical_url": {"title": "Canonical Url", "type": "string"}, "sample_types": {"title": "Sample Types", "type": "array", "items": {"type": "string"}}, "samples": {"title": "Samples", "type": "array", "items": {"$ref": "#/components/schemas/SampleSlimSchema"}}, "structured_metadata": {"title": "Structured Metadata", "type": "array", "items": {"$ref": "#/components/schemas/AnimalStructuredDatumSchema"}}}, "required": ["canonical_url", "sample_types", "samples", "structured_metadata"]}, "AnimalSlimSchema": {"title": "AnimalSlimSchema", "type": "object", "properties": {"accession": {"title": "Accession", "maxLength": 15, "type": "string"}, "system": {"title": "System", "maxLength": 10, "type": "string"}, "canonical_url": {"title": "Canonical Url", "type": "string"}, "sample_types": {"title": "Sample Types", "type": "array", "items": {"type": "string"}}}, "required": ["canonical_url", "sample_types"]}, "PagedAnimalSlimSchema": {"title": "PagedAnimalSlimSchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/AnimalSlimSchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}, "PagedSampleMetadataMarkerSchema": {"title": "PagedSampleMetadataMarkerSchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/SampleMetadataMarkerSchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}, "GenomeCatalogueSchema": {"title": "GenomeCatalogueSchema", "type": "object", "properties": {"id": {"title": "Id", "maxLength": 32, "type": "string"}, "title": {"title": "Title", "maxLength": 100, "type": "string"}, "biome": {"title": "Biome", "maxLength": 200, "type": "string"}, "related_mag_catalogue_id": {"title": "Related Mag Catalogue Id", "maxLength": 100, "type": "string"}, "system": {"title": "System", "maxLength": 10, "type": "string"}, "analysis_summaries": {"title": "Analysis Summaries", "type": "array", "items": {"$ref": "#/components/schemas/RelatedAnalysisSummarySchema"}}}, "required": ["title", "biome", "related_mag_catalogue_id", "system", "analysis_summaries"]}, "ViralCatalogueSchema": {"title": "ViralCatalogueSchema", "type": "object", "properties": {"id": {"title": "Id", "maxLength": 32, "type": "string"}, "title": {"title": "Title", "maxLength": 100, "type": "string"}, "biome": {"title": "Biome", "maxLength": 200, "type": "string"}, "system": {"title": "System", "maxLength": 10, "type": "string"}, "related_genome_catalogue": {"$ref": "#/components/schemas/GenomeCatalogueSchema"}, "analysis_summaries": {"title": "Analysis Summaries", "type": "array", "items": {"$ref": "#/components/schemas/RelatedAnalysisSummarySchema"}}, "related_genome_catalogue_url": {"title": "Related Genome Catalogue Url", "type": "string"}}, "required": ["title", "biome", "system", "related_genome_catalogue", "analysis_summaries", "related_genome_catalogue_url"]}, "AnalysisSummarySchema": {"title": "AnalysisSummarySchema", "type": "object", "properties": {"title": {"title": "Title", "maxLength": 200, "type": "string"}, "canonical_url": {"title": "Canonical Url", "type": "string"}, "samples": {"title": "Samples", "type": "array", "items": {"$ref": "#/components/schemas/SampleSlimSchema"}}, "genome_catalogues": {"title": "Genome Catalogues", "type": "array", "items": {"$ref": "#/components/schemas/GenomeCatalogueSchema"}}, "viral_catalogues": {"title": "Viral Catalogues", "type": "array", "items": {"$ref": "#/components/schemas/ViralCatalogueSchema"}}}, "required": ["title", "canonical_url", "samples", "genome_catalogues", "viral_catalogues"]}, "PagedAnalysisSummarySchema": {"title": "PagedAnalysisSummarySchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/AnalysisSummarySchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}, "PagedGenomeCatalogueSchema": {"title": "PagedGenomeCatalogueSchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/GenomeCatalogueSchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}, "GenomeSchema": {"title": "GenomeSchema", "type": "object", "properties": {"accession": {"title": "Accession", "maxLength": 15, "type": "string"}, "cluster_representative": {"title": "Cluster Representative", "maxLength": 15, "type": "string"}, "taxonomy": {"title": "Taxonomy", "maxLength": 200, "type": "string"}, "metadata": {"title": "Metadata", "type": "object"}, "annotations": {"title": "Annotations", "type": "object"}, "representative_url": {"title": "Representative Url", "type": "string"}}, "required": ["cluster_representative", "taxonomy", "representative_url"]}, "PagedGenomeSchema": {"title": "PagedGenomeSchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/GenomeSchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}, "GenomeSampleContainmentSchema": {"title": "GenomeSampleContainmentSchema", "type": "object", "properties": {"sample": {"title": "Sample", "type": "string"}, "containment": {"title": "Containment", "default": 0, "type": "number"}}, "required": ["sample"]}, "GenomeWithContainingSamplesSchema": {"title": "GenomeWithContainingSamplesSchema", "type": "object", "properties": {"accession": {"title": "Accession", "maxLength": 15, "type": "string"}, "cluster_representative": {"title": "Cluster Representative", "maxLength": 15, "type": "string"}, "taxonomy": {"title": "Taxonomy", "maxLength": 200, "type": "string"}, "metadata": {"title": "Metadata", "type": "object"}, "annotations": {"title": "Annotations", "type": "object"}, "representative_url": {"title": "Representative Url", "type": "string"}, "samples_containing": {"title": "Samples Containing", "type": "array", "items": {"$ref": "#/components/schemas/GenomeSampleContainmentSchema"}}}, "required": ["cluster_representative", "taxonomy", "representative_url", "samples_containing"]}, "PagedViralCatalogueSchema": {"title": "PagedViralCatalogueSchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/ViralCatalogueSchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}, "ViralFragmentSchema": {"title": "ViralFragmentSchema", "type": "object", "properties": {"id": {"title": "ID", "maxLength": 100, "type": "string"}, "contig_id": {"title": "Contig ID", "maxLength": 100, "type": "string"}, "mgnify_analysis_accession": {"title": "Mgnify Analysis Accession", "maxLength": 12, "type": "string"}, "start_within_contig": {"title": "Start Within Contig", "type": "integer"}, "end_within_contig": {"title": "End Within Contig", "type": "integer"}, "metadata": {"title": "Metadata", "type": "object"}, "viral_type": {"title": "Viral Type", "maxLength": 15, "type": "string"}, "taxonomy": {"title": "Taxonomy", "maxLength": 100, "type": "string"}, "cluster_representative": {"$ref": "#/components/schemas/ViralFragmentSchema"}, "contig_url": {"title": "Contig Url", "minLength": 1, "maxLength": 65536, "format": "uri", "type": "string"}, "mgnify_analysis_url": {"title": "Mgnify Analysis Url", "minLength": 1, "maxLength": 65536, "format": "uri", "type": "string"}, "gff_url": {"title": "Gff Url", "type": "string"}}, "required": ["contig_id", "mgnify_analysis_accession", "start_within_contig", "end_within_contig", "viral_type", "cluster_representative", "contig_url", "mgnify_analysis_url", "gff_url"]}, "PagedViralFragmentSchema": {"title": "PagedViralFragmentSchema", "type": "object", "properties": {"items": {"title": "Items", "type": "array", "items": {"$ref": "#/components/schemas/ViralFragmentSchema"}}, "count": {"title": "Count", "type": "integer"}}, "required": ["items", "count"]}}}, "servers": null}