Introduction
Welcome to the ATCC Genome Portal API Documentation. ATCC provides a secure API for ATCC's Supporting Members, to allow access to 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 Details |
| GET | A detailed description of the assembly and its metadata. (You'll find the primary assembly ID in Genome Details. |
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 your API key to authenticate requests.
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:
"X-API-Key: {API_KEY}"
See below for examples of using these for authentication.
For people with legacy JWT tokens, you'll find those when logged in to the ATCC genome portal, at https://genomes.atcc.org/profile. In place of your X-API-Key: {API_KEY}, you would use 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 "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 "X-API-Key: {API_KEY}" \
"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 "X-API-Key: {API_KEY}" \
-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 "X-API-Key: {API_KEY}" \
"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 "X-API-Key: {API_KEY}" \
"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"
}
}
}
}