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 |
| GET | A paginate list of Genomes |
Genome Details |
| GET | A detailed description of the genome and its metadata |
Genome Search |
| POST | A list of all genomes that match search criteria |
Assembly Download |
| GET | Provides a temporary link to download the genome's assembly |
Annotations Download |
| 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"
}
}
}
}