Introduction

Welcome to the ATCC Genome Portal API Documentation. ATCC provides a secure API for accessing the contents of the Genome Portal.

Endpoint Summary:

Name

Endpoint

Method

Description

Genomes

/api/genomes

GET

A paginate list of Genomes

Genome Details

/api/genomes/{ID}

GET

A detailed description of the genome and its metadata

Genome Search

/api/genomes/search

POST

A list of all genomes that match search criteria

Assembly Download

/api/genomes/{ID}/download_assembly

GET

Provides a temporary link to download the genome's assembly

Annotations Download

/api/genomes/{ID}/download_annotations

GET

Provides a temporary link to download the genome's annotations

See below for a detailed description of each endpoint and a complete API schema

Authentication

The Genome Portal uses your JWT to authenticate requests. To locate your JWT, go to your profile page on the Genome Portal here: https://genomes.atcc.org/profile and copy your JWT to your clipboard. You must be logged in to access your JWT. Please note, individual JWTs are only valid for 15 minutes before needing to be replaced.

On all API requests, set an Authorization header that uses your JWT as a Bearer token. It should look like this:

"Authentication: Bearer {TOKEN}"


Endpoints

Genomes

Method: GET

Parameters:

Parameter

Optional/Required

Type

page

Optional

Integer

page_size

Optional

Integer

The /api/genomes endpoint provides a paginated list of all available Genomes with high-level details. It accepts optional query parameters for "page" and "page_size". It returns an array of Genome objects.

Example:

curl -H "Authorization: Bearer {TOKEN}" \
"https://genomes.atcc.org/api/genomes?page=2"

Example Response:

[
{
"attributes": {
"asm_launch": true,
"atcc_metadata": {
"antibiotic_resistance": null,
"antigenic_prop": null,
"bsl": 2,
"catalog_number": "700824",
"genotype": "cagA+ vacA+",
"gold": true,
"isolation_new_web": "Patient with a duodenal ulcer United States 1994",
"notes": null,
"sequencing_technology": null,
"type_strain": false
},
"biosafety_level": 2,
"catalog_number": "700824",
"dna_item": "700824D-5",
"product_url": "https://www.atcc.org/Products/All/700824",
"source_item": "700824"
},
"collection_name": "bacteriology",
"description": null,
"id": "21846cfe916b4f18",
"name": "ATCC® 700824™",
"preferred_taxonomy_name": null,
"product_id": "700824",
"product_url": "https://www.atcc.org/Products/All/700824",
"taxon_name": "Helicobacter pylori"
},
{
"attributes": {
"asm_launch": true,
"atcc_metadata": {
"antibiotic_resistance": null,
"antigenic_prop": null,
"bsl": 1,
"catalog_number": "4357",
"genotype": null,
"gold": true,
"isolation_new_web": "Human",
"notes": null,
"sequencing_technology": null,
"type_strain": false
},
"biosafety_level": 1,
"catalog_number": "4357",
"dna_item": "4357D-5",
"product_url": "https://www.atcc.org/Products/All/4357",
"source_item": "4357"
},
"collection_name": "bacteriology",
"description": null,
"id": "08754bd7a402442f",
"name": "ATCC® 4357™",
"preferred_taxonomy_name": null,
"product_id": "4357",
"product_url": "https://www.atcc.org/Products/All/4357",
"taxon_name": "Lactobacillus acidophilus"
},
...
]

Genome Details

Method: GET

Parameters:

Parameter

Optional/Required

Type

id

Required

String

The /api/genomes/{id} endpoint requires an ID parameter. It returns a detailed description of the requested genome and its metadata

Example:

curl -H "Authorization: Bearer {TOKEN}" \
"https://genomes.atcc.org/api/genomes/21846cfe916b4f18"

Example Response:

{"attributes":{"asm_launch":true,"atcc_metadata":{"antibiotic_resistance":null,"antigenic_prop":null,"bsl":2,"catalog_number":"700824","genotype":"cagA+ vacA+","gold":true,"isolation_new_web":"Patient with a duodenal ulcer United States 1994","notes":null,"sequencing_technology":null,"type_strain":false},"biosafety_level":2,"catalog_number":"700824","dna_item":"700824D-5","product_url":"https://www.atcc.org/Products/All/700824","source_item":"700824"},"collection_name":"bacteriology","description":null,"id":"21846cfe916b4f18","name":"ATCC\u00ae 700824\u2122","preferred_taxonomy_name":null,"primary_assembly":{"attributes":{"contig_lengths":[1645141],"length":1645141,"qc_statistics":{"assembly_level":"Complete","assembly_statistics":{"filtered":{"contig_statistics":[{"ambiguous_nucleotide_count":0,"circular":true,"gc_content":0.3918648918238619,"id":"1","illumina_depth":{"max":1618,"mean":584.114323939407,"median":613,"min":5,"stdev":210.4346891828517},"length":1645141,"ont_depth":{"max":534,"mean":277.2999390325814,"median":278,"min":3,"stdev":38.89479636989169}}],"gc_content":0.3918648918238619,"max_contig_length":1645141,"mean_contig_length":1645141,"median_contig_length":1645141,"min_contig_length":1645141,"n50":1645141,"total_circular_contigs":1,"total_contig_length":1645141,"total_contigs":1},"unfiltered":{"gc_content":0.3918648918238619,"max_contig_length":1645141,"mean_contig_length":1645141,"median_contig_length":1645141,"min_contig_length":1645141,"n50":1645141,"total_circular_contigs":1,"total_contig_length":1645141,"total_contigs":1}},"checkm_results":{"completeness":99.76525821596243,"contamination":0.0},"path":"assembly.fasta","sequencing_statistics":{"illumina":{"depth":{"max":1618,"mean":584.114323939407,"median":613,"min":5,"stdev":210.4346891828517},"reads":{"N50":null,"ambiguous_bases":4461,"median_quality":38,"median_read_length":249,"position_specific_quality_scores":{"0":34,"1":34,"10":38,"100":38,"101":38,"102":38,"103":38,"104":38,"105":38,"106":38,"107":38,"108":38,"109":38,"11":38,"110":38,"111":38,"112":38,"113":38,"114":38,"115":38,"116":38,"117":38,"118":38,"119":38,"12":38,"120":38,"121":38,"122":38,"123":38,"124":38,"125":38,"126":38,"127":38,"128":38,"129":38,"13":38,"130":38,"131":38,"132":38,"133":38,"134":38,"135":38,"136":38,"137":38,"138":38,"139":38,"14":38,"140":38,"141":38,"142":38,"143":38,"144":38,"145":38,"146":38,"147":38,"148":38,"149":38,"15":38,"150":38,"151":38,"152":38,"153":38,"154":38,"155":38,"156":38,"157":38,"158":38,"159":38,"16":38,"160":38,"161":38,"162":38,"163":38,"164":38,"165":38,"166":38,"167":38,"168":38,"169":38,"17":38,"170":38,"171":38,"172":38,"173":38,"174":38,"175":38,"176":38,"177":38,"178":38,"179":38,"18":38,"180":38,"181":38,"182":38,"183":38,"184":38,"185":38,"186":38,"187":38,"188":38,"189":38,"19":38,"190":38,"191":38,"192":38,"193":38,"194":38,"195":38,"196":38,"197":38,"198":38,"199":38,"2":34,"20":38,"200":38,"201":38,"202":38,"203":38,"204":38,"205":38,"206":38,"207":38,"208":38,"209":38,"21":38,"210":38,"211":38,"212":38,"213":38,"214":38,"215":38,"216":38,"217":38,"218":38,"219":38,"22":38,"220":38,"221":38,"222":38,"223":38,"224":38,"225":38,"226":38,"227":38,"228":38,"229":38,"23":38,"230":38,"231":38,"232":38,"233":38,"234":38,"235":37,"236":37,"237":37,"238":37,"239":37,"24":38,"240":37,"241":37,"242":37,"243":37,"244":37,"245":37,"246":37,"247":37,"248":37,"249":37,"25":38,"250":37,"251":37,"252":37,"253":37,"254":37,"255":37,"256":37,"257":37,"258":37,"259":37,"26":38,"260":37,"261":37,"262":37,"263":37,"264":37,"265":37,"266":37,"267":37,"268":37,"269":37,"27":38,"270":37,"271":37,"272":37,"273":37,"274":37,"275":37,"276":37,"277":37,"278":37,"279":37,"28":38,"280":37,"281":37,"282":37,"283":37,"284":37,"285":37,"286":37,"287":37,"288":37,"289":37,"29":38,"290":37,"291":37,"292":37,"293":37,"294":37,"295":37,"296":37,"297":37,"298":37,"299":37,"3":34,"30":38,"31":38,"32":38,"33":38,"34":38,"35":38,"36":38,"37":38,"38":38,"39":38,"4":34,"40":38,"41":38,"42":38,"43":38,"44":38,"45":38,"46":38,"47":38,"48":38,"49":38,"5":38,"50":38,"51":38,"52":38,"53":38,"54":38,"55":38,"56":38,"57":38,"58":38,"59":38,"6":38,"60":38,"61":38,"62":38,"63":38,"64":38,"65":38,"66":38,"67":38,"68":38,"69":38,"7":38,"70":38,"71":38,"72":38,"73":38,"74":38,"75":38,"76":38,"77":38,"78":38,"79":38,"8":38,"80":38,"81":38,"82":38,"83":38,"84":38,"85":38,"86":38,"87":38,"88":38,"89":38,"9":38,"90":38,"91":38,"92":38,"93":38,"94":38,"95":38,"96":38,"97":38,"98":38,"99":38},"total_bases":60,"total_reads":4401767}},"ont":{"depth":{"max":534,"mean":277.2999390325814,"median":278,"min":3,"stdev":38.89479636989169},"reads":{"N50":8915,"ambiguous_bases":0,"median_quality":13,"median_read_length":6369.5,"position_specific_quality_scores":{},"total_bases":5969,"total_reads":69810}}}}},"id":"e3e1c380fc82454c"},"product_id":"700824","product_url":"https://www.atcc.org/Products/All/700824","taxon":{"name":"Helicobacter pylori","parents":[{"name":"Helicobacter","rank":"genus","tax_id":209},{"name":"Helicobacteraceae","rank":"family","tax_id":72293},{"name":"Campylobacterales","rank":"order","tax_id":213849},{"name":"Epsilonproteobacteria","rank":"class","tax_id":29547},{"name":"delta/epsilon subdivisions","rank":"subphylum","tax_id":68525},{"name":"Proteobacteria","rank":"phylum","tax_id":1224},{"name":"Bacteria","rank":"superkingdom","tax_id":2},{"name":"cellular organisms","rank":"no rank","tax_id":131567}],"rank":"species","tax_id":210},"taxon_name":"Helicobacter pylori"}

Genome Search

Method: POST

Parameters:

Parameter

Optional/Required

Type

product_id

optional

String

text

optional

String

The /api/genomes/search endpoint allows for searching/filtering of Genomes in the Genome Portal by either ATCC "product_id" or by "text". Text will search a Genome's catalog_id, Name, and Taxon Name. Parameters must be included in the body of the POST request. The endpoint returns an array of Genome objects.

Example:

curl -H "Authorization: Bearer {TOKEN}" \
-d '{"text": "coli"}' \
-X POST \
"https://genomes.atcc.org/api/genomes/search"

Example Response:

[
{
"attributes": {
"atcc_metadata": {
"antibiotic_resistance": null,
"antigenic_prop": null,
"bsl": 1,
"catalog_number": "19853",
"drug_repository": null,
"genotype": null,
"gold": null,
"isolation_new_web": "Derived from Escherichia coli K-12, 3300 (ATCC 15767)",
"notes": null,
"sequencing_technology": null,
"type_strain": false
},
"product_url": "https://www.atcc.org/products/19853"
},
"collection_name": "bacteriology",
"description": null,
"id": "299ed8efb3904997",
"name": "ATCC® 19853™",
"preferred_taxonomy_name": null,
"product_id": "19853",
"product_url": "https://www.atcc.org/products/19853",
"taxon_name": "Escherichia coli"
},
{
"attributes": {
"atcc_metadata": {
"antibiotic_resistance": null,
"antigenic_prop": "Serotype O157:H7",
"bsl": 1,
"catalog_number": "43888",
"genotype": null,
"gold": null,
"isolation_new_web": "Human feces",
"notes": null,
"sequencing_technology": null,
"type_strain": false
},
"product_url": "https://www.atcc.org/Products/All/43888",
"scraped_organism_name": "Escherichia coli (Migula) Castellani and Chalmers (ATCC® 43888™)"
},
"collection_name": "bacteriology",
"description": null,
"id": "c6d599a2274d4c84",
"name": "ATCC® 43888™",
"preferred_taxonomy_name": null,
"product_id": "43888",
"product_url": "https://www.atcc.org/Products/All/43888",
"taxon_name": "Escherichia coli"
},
...
]

Assembly Download

Method: GET

Parameters:

Parameter

Optional/Required

Type

id

Required

String

The /api/genomes/{id}/download_assembly provides a time-limited link to download the Assembly for the requested genome.

Example:

curl -H "Authorization: Bearer {TOKEN}" \
"https://genomes.atcc.org/api/genomes/21846cfe916b4f18/download_assembly"

Example Response:

{"save_as_filename":"Helicobacter_pylori_ATCC_700824.fasta","url":"https://s3.amazonaws.com/refgenomics-userdata-production-encrypted/temporary-files/72h/assembly_12_genome_25_taxon_0/Helicobacter_pylori_ATCC_700824_assembly_e3e1c380fc82454c.fasta?response-content-disposition=attachment%3B%20filename%3D%22Helicobacter_pylori_ATCC_700824.fasta%22&AWSAccessKeyId=AKIA6GPUEB7CLCIK2XEI&Expires=1639675724&Signature=1PbS1aYH5tlYNnYBSFi3NvRuwr4%3D"}

Annotations Download

Method: GET

Parameters:

Parameter

Optional/Required

Type

id

Required

String

The /api/genomes/{id}/download_annotations provides a time-limited link to download the Annotations for the requested genome.

Example:

curl -H "Authorization: Bearer {TOKEN}" \
"https://genomes.atcc.org/api/genomes/21846cfe916b4f18/download_annotations"

Example Response:

{"save_as_filename":"Helicobacter_pylori_ATCC_700824.gbk","url":"https://s3.amazonaws.com/refgenomics-userdata-production-encrypted/temporary-files/72h/assembly_12_genome_25_taxon_0/Helicobacter_pylori_ATCC_700824_assembly_aadd907f7c114108.gbk?response-content-disposition=attachment%3B%20filename%3D%22Helicobacter_pylori_ATCC_700824.gbk%22&AWSAccessKeyId=AKIA6GPUEB7CLCIK2XEI&Expires=1639675836&Signature=Qf8nCXFBNFl1ztwjarK2%2FzyZEOM%3D"}


Complete Schema

{
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/api/genomes/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenomeDetail"
}
}
}
},
"default": {
"$ref": "#/components/responses/DEFAULT_ERROR"
}
},
"tags": [
"api"
]
},
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
]
},
"/api/genomes/{id}/download_annotations": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenomeDownload"
}
}
}
},
"default": {
"$ref": "#/components/responses/DEFAULT_ERROR"
}
},
"tags": [
"api"
]
},
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
]
},
"/api/genomes/{id}/download_assembly": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenomeDownload"
}
}
}
},
"default": {
"$ref": "#/components/responses/DEFAULT_ERROR"
}
},
"tags": [
"api"
]
},
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string",
"minLength": 1
}
}
]
},
"/api/genomes": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GenomesView"
}
}
}
},
"headers": {
"X-Pagination": {
"description": "Pagination metadata",
"schema": {
"$ref": "#/components/schemas/PaginationMetadata"
}
}
}
},
"default": {
"$ref": "#/components/responses/DEFAULT_ERROR"
},
"422": {
"$ref": "#/components/responses/UNPROCESSABLE_ENTITY"
}
},
"parameters": [
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
}
],
"tags": [
"api"
]
}
},
"/api/genomes/search": {
"post": {
"responses": {
"422": {
"$ref": "#/components/responses/UNPROCESSABLE_ENTITY"
},
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GenomesView"
}
}
}
},
"headers": {
"X-Pagination": {
"description": "Pagination metadata",
"schema": {
"$ref": "#/components/schemas/PaginationMetadata"
}
}
}
},
"default": {
"$ref": "#/components/responses/DEFAULT_ERROR"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Search"
}
}
}
},
"parameters": [
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"type": "integer",
"default": 1,
"minimum": 1
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"minimum": 1,
"maximum": 100
}
}
],
"tags": [
"api"
]
}
}
},
"info": {
"title": "Genome Portal API",
"version": "v1"
},
"tags": [
{
"name": "api",
"description": "Genome Portal API"
}
],
"openapi": "3.0.2",
"components": {
"schemas": {
"TaxonParent": {
"type": "object",
"properties": {
"rank": {
"type": "string"
},
"name": {
"type": "string"
},
"tax_id": {
"type": "integer"
}
}
},
"Taxon": {
"type": "object",
"properties": {
"rank": {
"type": "string"
},
"name": {
"type": "string"
},
"tax_id": {
"type": "integer"
},
"parents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaxonParent"
}
}
}
},
"AssemblyMetadata": {
"type": "object",
"properties": {
"length": {
"type": "integer"
},
"qc_statistics": {
"type": "object"
},
"contig_lengths": {
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"Assembly": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"attributes": {
"$ref": "#/components/schemas/AssemblyMetadata"
}
}
},
"GenomeDetail": {
"type": "object",
"properties": {
"taxon": {
"$ref": "#/components/schemas/Taxon"
},
"taxon_name": {
"readOnly": true
},
"attributes": {
"type": "object"
},
"collection_name": {
"readOnly": true
},
"name": {
"type": "string"
},
"preferred_taxonomy_name": {
"type": "string"
},
"product_url": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"product_id": {
"type": "string"
},
"primary_assembly": {
"$ref": "#/components/schemas/Assembly"
},
"description": {
"type": "string"
}
}
},
"Error": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Error message"
},
"errors": {
"type": "object",
"description": "Errors"
},
"status": {
"type": "string",
"description": "Error name"
},
"code": {
"type": "integer",
"description": "Error code"
}
}
},
"GenomeDownload": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"save_as_filename": {
"type": "string"
}
}
},
"GenomesView": {
"type": "object",
"properties": {
"taxon_name": {
"readOnly": true
},
"attributes": {
"type": "object"
},
"collection_name": {
"readOnly": true
},
"name": {
"type": "string"
},
"preferred_taxonomy_name": {
"type": "string"
},
"product_url": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"product_id": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"PaginationMetadata": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"total_pages": {
"type": "integer"
},
"first_page": {
"type": "integer"
},
"last_page": {
"type": "integer"
},
"page": {
"type": "integer"
},
"previous_page": {
"type": "integer"
},
"next_page": {
"type": "integer"
}
}
},
"Search": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
},
"text": {
"type": "string"
}
}
}
},
"responses": {
"DEFAULT_ERROR": {
"description": "Default error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"UNPROCESSABLE_ENTITY": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
}
}

Did this answer your question?