ATCC Genome Portal API Guide
This provides a guide on how to view, search, and download genomes using ATCC's API
Denise Lynch avatar
Written by Denise Lynch
Updated over a week ago

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 either your JWT or your API key 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. Alternatively, your API key can be found on the settings page of your One Codex account (https://app.onecodex.com/settings).

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

"Authentication: Bearer {TOKEN}"

If using your One Codex API key, you can instead set the following header:

"X-API-Key: {API_KEY}"

See below for examples of using these for authentication.


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:

Using a JWT token:

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

Using a One Codex API key:

curl -H "X-API-Key: {API_KEY}" \
"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?