One Codex API

The One Codex Developer Documentation

Welcome to the One Codex API documentation. Here you'll find comprehensive guides and documentation to help you start working with our genomic search and data platform as quickly as possible, as well as support if you need help.

Suggest Edits

Getting Started

A quick overview of the key concepts underlying the One Codex API

 

Beta Status

Warning: You're viewing the documentation for our new v1 API. While the v1 API is both easier to use and more full-featured than our v0 API, this is a beta release. While we do not plan to introduce any major breaking changes, it is possible that code developed against the v1 API may require minor updates as the API stabilizes. In general, however, the main anticipated to the v1 API are the addition of fields and resources, which should be strictly non-breaking. We expect a stable release in late 2016.

Welcome to the One Codex API!

One Codex is a data platform for microbial genomics, designed for the secure storage, sharing, and reproducible analysis of microbial next-generation sequencing data. Our API powers our web application and is intended to be simple enough for use in ad hoc bioinformatic analyses, but powerful enough to support integration into existing systems (e.g., LIMS) or extension by building applications directly atop the platform.

More concretely, the API allows users to upload NGS data (FASTA or FASTQ files), automatically determine their composition them using our best-in-class metagenomic classifier and database, start new analyses such as in silico panels and alignments, retrieve and build on top of these analyses, and much more.

Core Concepts

Across the API, there are several core concepts which map directly to the endpoints detailed below:

  • Samples: A Sample is a collection of genetic sequences (reads or contigs) that can be uploaded for analysis on the One Codex platform. At this time, we support uploading both FASTA and FASTQ files, which can optionally be compressed using gzip. Samples are owned by a User and may be described with Metadata records (both structured and free-form), annotated with Tags, and organized and shared via Projects.

  • Analyses: An analysis of an uploaded Sample. Several types of Analyses are supported on the platform today, and range from metagenomic classification (example) to panels for anti-microbial resistance (example). Types of analyses currently exposed via the API include Classifications, Panels, and Alignments. More are planned for the future.

  • Jobs: Analysis jobs represent an exact execution environment, analytic workflow, and accompanying reference data. Analyses are the result of a Job running against a specific Sample. All Jobs on the One Codex platform are strictly versioned and provide strong reproducibility guarantees, ensuring that an analyses of different samples can be readily compared and an analysis of the same sample can be repeated and reliably reproduced.

API Design & Accessing the API

Our API is a RESTful JSON API, and is self-described using JSON Schema. We hope that this format combined with an interactive API browser makes exploring and getting started with our API easy.

You can access the API using cURL, an HTTP client library in your preferred language, our Python client library, or our command line client.

Finally, if you find any part of the docs to be outdated or unclear, please don't be afraid to click the "Suggest Edits" link and let us know! We'd also be grateful to hear any suggestions, requests, or other questions you have. You're also always welcome to send us a note via the Chat button on the bottom right of these documentation pages and our API browser.

Suggest Edits

Authentication

Getting started with secure access to the One Codex API

 

The One Codex API uses HTTP Basic Auth for authentication by default. Only secure connections (HTTPS) are allowed. Use your API key as the username and an empty password to authenticate:

curl https://app.onecodex.com/api/v1/schema -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/schema

As our API supports access to public samples, projects, and analyses, unauthenticated access is permitted and may return empty result sets rather than a 401. If you see empty result sets, check that you're properly authenticated by accessing a protected resource, e.g., a private Sample owner by your account or the Account info resource (https://app.onecodex.com/api/v1/account).

Unauthenticated requests against protected routes will return a 401 Unauthorized. Unauthorized requests will return a 403 Forbidden. Unauthenticated or unauthorized requests for a protected resource (i.e., a private sample) may return a 404 Not Found in order to not expose the existence of private records.

{
    "message": "The server could not verify that you are authorized to access the URL requested.  You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required.",
    "status": 401
}

Protecting Your API Keys

Your API key is effectively a plain text password for accessing your uploads and analyses. Please keep it secure! If you lose your key, accidentally publish it to GitHub or another public place, or otherwise believe it could have been compromised, simply generate a new API key in the Settings pane of the One Codex web application. This will automatically revoke your old key.

Our API servers also support JWT-based authentication, which offer different security and usability tradeoffs. We plan to make JWT token generation available via the Settings page in the near future.

Locating your API key

You can find your API key under the Settings menu in the top-right corner of the One Codex web application:

Within the Settings menu, you should see a panel called Account Info & Security. Click the button under "Your API Key" to reveal your key. Again, keep this key secret!

Generating a new API key

If you lose access to your API key, accidentally publish it in a public place, or otherwise need to replace it, you can simply regenerate a new key on the Settings page:

Please note: You will need to update any code, configuration files, or environmental variables using the key.

Suggest Edits

API Documentation

 

The below sections provide more exhaustive documentation of the core One Codex API, but first a note and a warning:

Source of Truth: Our API Schema

Our API is self-described using JSON Schema, with the root schema for the API available at https://app.onecodex.com/api/v1/schema. While we do our best to keep this documentation accurate and up-to-date, in cases where there is a discrepancy between this documentation and the JSON schema, please defer to the API schema. However, we may occasionally offer features via the API that are explicitly not documented here – only documented features should be assumed to be stable.

Please let us know if you run into any issues by sending us a note or contacting us via the chat icon on the bottom right. Thanks!

Experimental Features: A Warning

While the v1 API is in beta, there are a small number of resource properties and routes that we're not 100% happy with yet. These are the only places where expect the possibility of a breaking change, e.g., by deleting, renaming, or moving a property.

In order to provide the most warning possible, we've flagged all such experimental properties and routes with an orange beaker icon ( ). If you're developing on top of our API and have any questions about different features' stability, please send us an email or send us a chat to the bottom right.

Suggest Edits

CLI & Client Library (Python)

 

To complement the API, we also provide an optional One Codex command line interface (CLI) and Python client library for more conveniently interacting with our API and platform.

The CLI supports several features not possible by using the raw API and cURL directly:

  • Saving and reloading API keys / login credentials
  • A more robust (and easier to use) upload process
  • Support for uploads >5GB
  • Support for multiple simultaneous file uploads

The command line interface is written in Python and accompanies our client library. It should be easily installable on most machines with the following command:

pip install onecodex==0.2.0

The CLI and accompanying onecodex Python client library support Python 2.7+ and Python 3.4+. Throughout the following documentation, we provide usage examples for the CLI and Python client libraries where applicable (labeled CLI and Python in the code snippets respectively).

Suggest Edits

Jupyter Notebooks

 

We're also happy to offer embedded Jupyter notebooks as part of the One Codex platform – facilitating both large-scale analyses and a nice environment for rapid development against our API. See our blog post announcing notebooks, request access while we're in preview, or take a look at an example notebook that uses the One Codex Python client library and v1 API.

Suggest Edits

Pagination

 

The One Codex API follows the basic pagination model of the GitHub API. Pages may be requested using the page and per_page query string arguments. The Link header lists links to the current, previous, next, first, and last pages. The X-Total-Count header contains a count of the total number of items:

HTTP/1.1 200 OK
Link: </api/v1/samples?page=1&per_page=20>; rel="self",
      </api/v1/samples?page=2&per_page=20>; rel="next"
      </api/v1/samples?page=3&per_page=20>; rel="last"
X-Total-Count: 46

The One Codex API communicates errors with standard HTTP status codes with details supplied in JSON objects. The following general pattern applies:

2XX: We received, processed, and accepted a request.

3XX: More action is required in order to complete the request. We use redirects sparingly.

4XX: Client error. Common errors relate to invalid parameters or our inability to find and serve the requested resource.

5XX: Server error. An error occurred on our system(s) while handling the request.

HTTP Status Codes

200 success
201 created
202 accepted
204 no_content
302 redirect
304 not_modified
400 bad_request
401 unauthorized
403 forbidden
404 not_found
405 method_not_allowed
409 conflict
412 precondition_failed
429 too_many_requests
500 internal_server_error
503 unavailable

Error Response

Field
Description

Message
string

An error message detailing why the request was unsuccessful.

Status
integer

HTTP status code

EXAMPLE ERROR

{
    "message": "The server could not verify that you are authorized to access the URL requested.  You either supplied the wrong credentials...",
    "status": 401
}
Suggest Edits

The Sample Resource

 

A Sample represents an underlying next-generation sequencing (NGS) data file, either in the form of a de-multiplexed FASTQ or a FASTA file. Often, there will be a single sample for each physical specimen, though in some cases there may be multiple Samples for each individual specimen (e.g., in the case of replicates).

Samples should be in FASTA or FASTQ format, optionally gzipped, and may be up to 100GB in size. Samples under 5GB can be uploaded to the One Codex platform with two direct API calls, while samples over 5GB require a slightly more complex three-step upload process.

The below table summarizes all of the properties for the Sample resource, with the JSON schema type of each property listed below in italics. Details on how to upload your NGS data, as well as retrieve and modify your Samples follows.

Property
Description

$uri
string

The sample ID encoded as an addressable URI

created_at
date-time

Timestamp for when the sample was created on the One Codex platform, encoded as a RFC 3339 timestamp

filename
string

The sample filename (e.g., "sample.fastq")

size
integer

The size of the uploaded file in bytes.

visibility
string

Samples may be public , shared , or private (no icon or if owner by another user and shared via a private project). The visibility of a sample controls access to a sample resource, any analyses (and corresponding jobs) performed on that sample, as well as the sample's metadata, project, and tags. As such, sensitive samples should always be "private" and shared across accounts using private projects.

owner
string

A reference to the user that uploaded and owns the sample, e.g., {"$ref": "/api/v1/users/5891ee65711c4d5e"}. Only sample owners can modify a sample (with some exceptions in the case of organization accounts configured for multiple users – please contact us if you'd like to discuss this use case).

metadata
string

A reference to a sample's accompanying Metadata, e.g., {"$ref": "/api/v1/metadata/481ad62997e647ba"}

project
string

A reference to the (optional) Project containing a sample. Samples can be part of zero or one projects.

tags
array of strings

An (optionally empty) array of references to Tags describing the sample. Tags are an additional unstructured organizational tool that complement Project and Metadata records.

Suggest Edits

Retrieve All Samples

 
gethttps://app.onecodex.com/api/v1/samples
curl https://app.onecodex.com/api/v1/samples -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/samples sort=="{'created_at': true}"
onecodex samples
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY")

# Retrieve all samples
samples = ocx.Samples.all()

# Retrieve samples matching a ?where query
samples_public = ocx.Samples.where(visibility='public')

# Alternative Mongo-style query support
samples_shared_and_public = ocx.Samples.where({'visibility': {'$in': ['public', 'shared']})
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "$uri": "/api/v1/samples/0ee172af60e84f61",
    "created_at": "2016-01-06T02:08:44.424525+00:00",
    "filename": "ERR757133.fastq.gz",
    "metadata": {
        "$ref": "/api/v1/metadata/dd0aa4fdd11541d1"
    },
    "owner": {
        "$ref": "/api/v1/users/5891ee65711c4d5e"
    },
    "primary_classification": {
        "$ref": "/api/v1/classifications/e18dc42b4f0d427b"
    },
    "project": {
        "$ref": "/api/v1/projects/fa7ec3db39ee4544"
    },
    "size": 10740746,
    "tags": [
        {
            "$ref": "/api/v1/tags/04104912f8724d44"
        },
        {
            "$ref": "/api/v1/tags/6b9583c6fc0b4fa9"
        },
        {
            "$ref": "/api/v1/tags/85e01f37fca24eec"
        }
    ],
    "visibility": "public"
	},
	...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all Sample instances. Returns a paginated list of Samples.

Suggest Edits

Retrieve A Sample

 
gethttps://app.onecodex.com/api/v1/samples/<id>
curl https://app.onecodex.com/api/v1/samples/0ee172af60e84f61 -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/samples/0ee172af60e84f61
onecodex samples 0ee172af60e84f61
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY")

# Retrieve Sample 0ee172af60e84f61
samples = ocx.Samples.get('0ee172af60e84f61')
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/samples/0ee172af60e84f61",
    "created_at": "2016-01-06T02:08:44.424525+00:00",
    "filename": "ERR757133.fastq.gz",
    "metadata": {
        "$ref": "/api/v1/metadata/dd0aa4fdd11541d1"
    },
    "owner": {
        "$ref": "/api/v1/users/5891ee65711c4d5e"
    },
    "primary_classification": {
        "$ref": "/api/v1/classifications/e18dc42b4f0d427b"
    },
    "project": {
        "$ref": "/api/v1/projects/fa7ec3db39ee4544"
    },
    "size": 10740746,
    "tags": [
        {
            "$ref": "/api/v1/tags/04104912f8724d44"
        },
        {
            "$ref": "/api/v1/tags/6b9583c6fc0b4fa9"
        },
        {
            "$ref": "/api/v1/tags/85e01f37fca24eec"
        }
    ],
    "visibility": "public"
}

Path Params

id
string
required

Sample ID

 

GET a single sample by its ID.

Suggest Edits

Retrieve Public Samples

 
gethttps://app.onecodex.com/api/v1/samples/public
curl https://app.onecodex.com/api/v1/samples/public -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/samples/public sort=="{'created_at': true}"
# Not yet implemented in v0.2.0a1.
# Current interface is:
# 
# ocx.Samples.search_public()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "$uri": "/api/v1/samples/0761be49f8104be2",
        "created_at": "2015-02-04T18:53:42+00:00",
        "filename": "SRR1106129.fastq.gz",
        "metadata": {
            "$ref": "/api/v1/metadata/9d5566496dec4f6d"
        },
        "owner": {
            "$ref": "/api/v1/users/767b0e0da9ab4312"
        },
        "primary_classification": {
            "$ref": "/api/v1/classifications/1c2beb9837d648f7"
        },
        "project": null,
        "size": 3504540871,
        "tags": [
            {
                "$ref": "/api/v1/tags/dbcf5b98bca54a16"
            }
        ],
        "visibility": "public"
    },
		...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all publicly-listed samples. Returns a paginated list of Samples.

Suggest Edits

Uploading Samples

 

Samples under 5GB

Samples under 5GB may be uploaded via the REST API or by using the One Codex CLI or Python client library.

The latter two options are simpler and thus recommended (and also support automatic interleaving and validation of your FASTA/Qs). To upload with the CLI, simply:

# If you haven't previously logged in, the following command
# will prompt you for your username and password and then 
# save a ~/.onecodex file with your API key
onecodex login

# This command will automatically upload all FASTQs into your account,
# prompting you to interleave any paired end data (recommended) if applicable
onecodex upload $LIST_OR_GLOB_OF_YOUR_SAMPLES

Uploading via the REST API consists of 3 steps:

Samples over 5GB

For samples over 5GB an unstable REST API interface is available, but we recommend uploading these samples using the One Codex CLI or the latest version of the One Codex Python client library. Using the CLI, uploads of any size are supported by simply calling onecodex upload my_large_sample.fastq.gz.

Suggest Edits

Starting an Upload

 
posthttps://app.onecodex.com/api/v1/samples/init_upload
curl -u $ONE_CODEX_API_KEY: -X POST -H "Content-Type: application/json" -d '{"filename": "HiSeq.fa", "size": 10000}' https://app.onecodex.com/api/v1/samples/init_upload
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/samples/init_upload filename=HiSeq.fa size:=10000
# Note that handles the entire upload, not just init_upload.
# The Python client library also supports uploads >5GB.
ocx.Samples.upload("HiSeq.fa")  
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
# Response format of additional fields varies
# by upload_type. A standard upload will 
# return an upload_url to a cloud block 
# storage service (currently Amazon S3, 
# though this is not guaranteed), as well as
# a set of additional fields to be used 
# in POSTing to the upload url.
{
    "sample_id": "0ee172af60e84312",
    "upload_url": "https://onecodex-userdata-production-encrypted.s3.amazonaws.com",
    "additional_fields": {
      ...
    }
}

Body Params

filename
string
required

The filename of the sample to be uploaded. FASTA and FASTQ records, optionally gzipped (and ending in .gz or .gzip) are supported. Filenames should only contain alphanumeric characters, dashes, underscores, and periods.

size
int32
required

The size of the file in bytes.

upload_type
string

The type of upload to initiate. Currently only standard uploads (for files <=5GB) are supported via the init_upload route.

 

Start an upload by POSTing the filename and size to /samples/init_upload. To actually perform the upload it is then necessary to transmit the file to the provided upload_url, with any additional_fields as needed. This second step varies depending on the upload_type. Currently only a standard upload type is available.

Performing the actual upload – "standard" upload type

The standard upload involves POSTing a sample up to 5GB in size to a provided HTTPS URL. The Content-Type should be multipart/form-data and the additional_fields should be included in the POST body.

The workflow using httpie or Python requests is:

# Start the upload
http --auth $ONE_CODEX_API_KEY: POST \ 
https://app.onecodex.com/api/v1/samples/init_upload \
filename=HiSeq_accuracy.fa size:=1189333

# Returns a 200 response with the following JSON body:
# {
#     "additional_fields": {
#         "AWSAccessKeyId": "XXXXXXXXXXXXXXXXXXXX",
#         "acl": "private",
#         "key": "user_xxxxxxxxxxxxxxxx/file_yyyyyyyyyyyyyyyy/${filename}",
#         "policy": "CiAgICAgICAgICAgAgICAgICB7ImJ1Y2tldCI6ICJyZWZnZW5vbWljcy11c2VyZGF0YS1kZXYtZW5jcnlwdGVkIiB9LAogICAS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9LAogICAgICAgICAgICAgICAgWyJzdGFydHMtd2l0aCIsICIka2V5IiwgInVzZXJfNGFkYTU2MTAzZDlhNDhiOC9maWxlXzI4NDU5NTA4NTkyYTQ4MWMvIl0sCiAgICAgICAgICAgICAgICB7InN1Y2Nlc3NfYWN0aW9uX3N0YXR1cyI6ICIyMDEifSwKICAgICAgICAgICAgICBdCiAgICAgICAgICAgIH0KICAgICAgICAgICAg",
#         "signature": "ELADfQLgxXXXXXXXXx/5D99Q9AY=",
#         "success_action_status": 201,
#         "x-amz-server-side-encryption": "AES256"
#     },
#     "sample_id": "28459508592a481c",
#     "upload_url": "https://refgenomics-userdata-dev-encrypted.s3.amazonaws.com"
# }

http -f POST \ 
    https://sample-upload-bucket.s3.amazonaws.com \
    AWSAccessKeyId="XXXXXXXXXXXXXXXXXXXX" acl="private" \ 
    key="user_xxxxxxxxxxxxxxxx/file_yyyyyyyyyyyyyyyy/${filename}" \ 
    policy="CiAgICAgICAgICAgAgICAgICB7ImJ1Y2tldCI6ICJyZWZnZW5vbWljcy11c2VyZGF0YS1kZXYtZW5jcnlwdGVkIiB9LAogICAS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9LAogICAgICAgICAgICAgICAgWyJzdGFydHMtd2l0aCIsICIka2V5IiwgInVzZXJfNGFkYTU2MTAzZDlhNDhiOC9maWxlXzI4NDU5NTA4NTkyYTQ4MWMvIl0sCiAgICAgICAgICAgICAgICB7InN1Y2Nlc3NfYWN0aW9uX3N0YXR1cyI6ICIyMDEifSwKICAgICAgICAgICAgICBdCiAgICAgICAgICAgIH0KICAgICAgICAgICAg" \
    signature="ELADfQLgxXXXXXXXXx/5D99Q9AY=" success_action_status:=201 \
    x-amz-server-side-encryption="AES256" \ 
    file@HiSeq_accuracy.fa
    
# Returns a 201 response

# Confirm the upload (see below)
http --auth $ONE_CODEX_API_KEY: POST \ 
    https://app.onecodex.com/api/v1/samples/confirm_upload \
    sample_id="28459508592a481c"
# Start the upload
resp = requests.post('https://app.onecodex.com/api/v1/init_upload', 
                     json={'filename': 'HiSeq_accuracy.fa', 
                           'size': os.path.getsize('HiSeq_accuracy.fa')},
                     auth=(os.getenv('ONE_CODEX_API_KEY'), '')
                    ).json()

# Perform the upload (should return a 201)
requests.post(resp['upload_url'], data=resp['additional_fields'], 
             files={'file': open('HiSeq_accuracy.fa')})

# Finally, confirm the upload (should return a 200)
requests.post('https://app.onecodex.com/api/v1/samples/confirm_upload', 
              json={'sample_id': resp['sample_id']},
              auth=(os.getenv('ONE_CODEX_API_KEY'), ''))
Suggest Edits

Confirming an Upload

 
posthttps://app.onecodex.com/api/v1/samples/confirm_upload
curl -u $ONE_CODEX_API_KEY: -X POST -H "Content-Type: application/json" -d '{"sample_id": "0ee172af60e84312"}' https://app.onecodex.com/api/v1/samples/confirm_upload
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/samples/init_upload sample_id=0ee172af60e84312
# Note that handles the entire upload, not just confirm_upload.
# The Python client library also supports uploads >5GB.
ocx.Samples.upload("HiSeq.fa")  
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "success": true,
  "message": "Upload successfully completed. Processing underway...",
  "sample": {
    "$ref": "/api/v1/samples/0ee172af60e84312"
  }
}

Body Params

sample_id
string
required

The sample_id returned by /samples/init_upload. Note that this is a proposed sample ID and the sample will not be accessible via /samples/<id> until the upload is confirmed.

upload_type
string

The type of upload to initiate. Currently only standard uploads (for files <=5GB) are supported via the init_upload route. This should match the upload_type used for /samples/init_upload.

 

Confirms the upload. See Starting an Upload for more details on the full upload workflow.

Suggest Edits

Updating Samples

 
patchhttps://app.onecodex.com/api/v1/samples/<id>
curl -u $ONE_CODEX_API_KEY: -X PATCH -H "Content-Type: application/json" -d '{"visibility": "public"}' https://app.onecodex.com/api/v1/samples/0ee172af60e84f61
# Update visibility
http --auth $ONE_CODEX_API_KEY: PATCH https://app.onecodex.com/api/v1/samples/0ee172af60e84f61 visibility=public

# Assign to a project (note: `project=fa7ec3db39ee4544` also works)
http --auth $ONE_CODEX_API_KEY: PATCH https://app.onecodex.com/api/v1/samples/0ee172af60e84f61 project:='{"$ref": "/api/v1/projects/fa7ec3db39ee4544"}'

# Remove project
http --auth $ONE_CODEX_API_KEY: PATCH https://app.onecodex.com/api/v1/samples/0ee172af60e84f61 project:=null 
sample = ocx.Samples.get('0ee172af60e84f61')
sample.visibility = "public"
sample.save()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/samples/0ee172af60e84f61",
    "created_at": "2016-01-06T02:08:44.424525+00:00",
    "filename": "ERR757133.fastq.gz",
    "metadata": {
        "$ref": "/api/v1/metadata/dd0aa4fdd11541d1"
    },
    "owner": {
        "$ref": "/api/v1/users/5891ee65711c4d5e"
    },
    "primary_classification": {
        "$ref": "/api/v1/classifications/e18dc42b4f0d427b"
    },
    "project": {
        "$ref": "/api/v1/projects/fa7ec3db39ee4544"
    },
    "size": 10740746,
    "tags": [
        {
            "$ref": "/api/v1/tags/04104912f8724d44"
        },
        {
            "$ref": "/api/v1/tags/6b9583c6fc0b4fa9"
        },
        {
            "$ref": "/api/v1/tags/85e01f37fca24eec"
        }
    ],
    "visibility": "public"
}

Path Params

id
string
required

Sample ID

Body Params

visbility
string

Set the visibility for a sample. Valid values are private, shared, and public.

project
object

Reference to a project, e.g., {"$ref": "/api/v1/projects/fa7ec3db39ee4544"}. Set to null to remove a sample from a project.

tags
array

Array of references to tags for the sample, e.g., [{"$ref": "/api/v1/tags/04104912f8724d44"}]. Note that PATCHing the tags replaces all tags currently on the sample with the new list of tags. Pass an empty array to remove all tags from the sample.

 

In general, samples should be considered an immutable resource, but how they are shared may be updated by changing their visibility and project properties and the tags associated with them may also be changed. All other sample attributes are read-only, and the associated metadata record should be used for storing additional (mutable) structured information about a sample.

Additional authorization checks: Note that PATCHing to update the sample's visibility triggers additional account- and organization-level checks. For certain accounts (e.g., those in which PII is deposited), it may not be possible to make samples shared or public. Please contact us to discuss setting additional restrictions on sample-sharing for your or your organization's account. Similarly, users may only add their samples to projects for which they have appropriate project-level permissions.

Suggest Edits

Downloading Sequence Data

 
posthttps://app.onecodex.com/api/v1/samples/<id>/download_uri
# Retrieve a download URI, note you may receive a 402 error
# if on a standard plan and *outside* of a Jupyter notebook environment
curl -u $ONE_CODEX_API_KEY: -X POST https://app.onecodex.com/api/v1/samples/0ee172af60e84f61/download_uri
# Retrieve a download URI, note you may receive a 402 error
# if on a standard plan and *outside* of a Jupyter notebook environment
http --auth $ONE_CODEX_API_KEY: POST https://app.onecodex.com/api/v1/samples/0ee172af60e84f61/download_uri
sample = ocx.Samples.get('0ee172af60e84f61')
sample.download()  # Optionally pass a new filename to .download()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK 402 Payment Required
{
	"download_ur": "https://a-presigned-download-url.onecodex.com",
  "expires_in_hours": 4
}
{
    "message": "Downloading samples is not allowed for your given plan or environment. Please contact help@onecodex.com if you have questions.", 
    "status": 402
}

Path Params

id
string
required

Sample ID

 

Retrieve the sequence data (i.e., original FASTA or FASTQ file) for an individual sample. First POST to the download_uri endpoint for the individual sample. Then download the provided pre-signed download_uri link within the provided link expiration timeframe.

For premium platform account users, One Codex also acts as a secure, highly redundant backup copy of your sequence data and permits ad hoc retrieval of that data. Within our embedded Jupyter Notebooks, the underlying sequence data may be freely downloaded and further analyzed as it does result in bandwidth egress charges from our cloud environment.

Note that this route is a POST because it may incur retrieval charges for large amounts of data and so should not be repeatedly retried. Care should also be taken in porting code using the download_uri route from a notebook environment on the One Codex platform to an external environment (where downloads may be unavailable depending on your platform account level).

Suggest Edits

The Metadata Resource

 

Metadata resources provide a means for adding structured metadata to your samples. The Metadata resource include a number of default fields, and can also be extended with arbitrary custom metadata. Permissions on metadata follow the Samples they describe – i.e., the Metadata resource for a public sample will be publicly accessible. Here is an example metadata entry:

The metadata editing modal on the One Codex web application. Note that the Project is actually a property on the Sample resource.

The metadata editing modal on the One Codex web application. Note that the Project is actually a property on the Sample resource.

Metadata include the following properties:

Property
Description

$uri
string

The metadata ID encoded as an addressable URI. Note that this is distinct from the sample ID (see sample below).

name
string

An optional name for the sample name that will be used for display across One Codex (up to 255 characters). When missing, the sample's filename will be used.

description
string

Free-form text description of the sample.

location_lat
number

The latitude (-9090.0) of the sample location. By convention, we recommend using this for the location in which the physical specimen was collected.

location_lon
number

The longitude (-180.0180.0) of the sample location.

location_string
string

A string describing the location. Currently, we do not attempt to automatically parse the lat/lon from these ( ). The One Codex web application does however set all 3 via a map.

platform
string

An enum with the name of the sequencing platform. Currently, the following values are valid: ["Illumina MiSeq", "Illumina HiSeq", "Illumina NextSeq 500", "Illumina Genome Analyzer II", "PacBio", "Oxford Nanopore MinION", "Ion Torrent", "Ion Proton", "SOLiD", "454 sequencing", "Sanger", null].

library_type
string

An enum with the sample type. This is currently limited to the following values: ["WGS", "Targeted/16S", "Other", null].

sample_type
string

An enum with the sample type. This is currently limited to the following values: ["Isolate", "Metagenomic", "Other", null].

date_collected
date-time

Timestamp for when the sample was collected.

date_sequenced
date-time

Timestamp for when the sample was sequenced.

external_sample_id
string

An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters.

starred
boolean

Whether the sample has been starred by the user within the One Codex web application.

custom
object

Arbitrary metadata is supported as part of a custom object. custom has two constraints: (1) it must have a depth of one (i.e., no nested records); and (2) only strings, numbers, boolean, and null values are supported as values. Example:

{
  "lab_tech": "Linus Pauling",
  "amplicon_scheme": "V3/V4"
}
Suggest Edits

The Tag Resource

 

In addition to support for structured metadata via the Metadata resource, the One Codex platform supports attaching arbitrary labels or tags to samples. These tags are displayed in the Samples view of the One Codex web application.

Users can create and apply arbitrary tags to their samples, and then use those to query for or filter to a subset of samples. The One Codex platform also automatically applies tags that reflect underlying annotations we are able to generate from your microbial NGS data. Tags on a sample may be updated by PATCHing an updated listed of tags to update a sample record (see Updating Samples).

For example, if you upload a FASTQ file from an E. coli isolate, you should see the system automatically tag is as E. coli, tag it as an "isolate", and then automatically run and tag the sample with its MLST type.

By convention, tags created automatically by our system have lighter colors and dark text. User-created tags have bolder colors with white text.

Property
Description

$uri
string

The tag ID encoded as an addressable URI.

name
string

The tag label or name.

Suggest Edits

Retrieve All Metadata

 
gethttps://app.onecodex.com/api/v1/metadata
curl https://app.onecodex.com/api/v1/metadata -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/metadata where=="{'library_type': 'Targeted/16S'}"
ocx.Metadata.all()

# [<Metadata 8f869e3d72114ad1>,
#  <Metadata 481ad62997e647ba>,
#  <Metadata 78eaf2fbfb334bcf>,
#  <Metadata e181bdcbd4c54427>,
#  <Metadata dd0aa4fdd11541d1>,
# ...]
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "$uri": "/api/v1/metadata/8f869e3d72114ad1",
        "custom": {},
        "date_collected": "2016-10-01T07:00:00+00:00",
        "date_sequenced": "2016-10-05T07:00:00+00:00",
        "description": "CHILD gut microbiome and asthma",
        "external_sample_id": null,
        "library_type": "Targeted/16S",
        "location_lat": 39.9525839,
        "location_lon": -75.1652215,
        "location_string": "Philadelphia, PA, USA",
        "name": null,
        "platform": "Illumina HiSeq",
        "sample": {
            "$ref": "/api/v1/samples/05631a0d9b084c43"
        },
        "sample_type": "Metagenomic",
        "starred": false
    }
    {
        "$uri": "/api/v1/metadata/481ad62997e647ba",
        "custom": {},
        "date_collected": null,
        "date_sequenced": null,
        "description": "CHILD gut microbiome and asthma",
        "external_sample_id": null,
        "library_type": "Targeted/16S",
        "location_lat": null,
        "location_lon": null,
        "location_string": null,
        "name": null,
        "platform": "Illumina HiSeq",
        "sample": {
            "$ref": "/api/v1/samples/87171d1b933846a6"
        },
        "sample_type": "Metagenomic",
        "starred": true
    },
    ...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all metadata records. Returns a paginated list of Metadata records.

Suggest Edits

Retrieve A Metadata Record

 
gethttps://app.onecodex.com/api/v1/metadata/<id>
curl https://app.onecodex.com/api/v1/metadata/8f869e3d72114ad1 -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/metadata/8f869e3d72114ad1 
ocx.Metadata.get('8f869e3d72114ad1')

# Returns <Metadata 8f869e3d72114ad1>
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/metadata/8f869e3d72114ad1",
    "custom": {},
    "date_collected": "2016-10-01T07:00:00+00:00",
    "date_sequenced": "2016-10-05T07:00:00+00:00",
    "description": "CHILD gut microbiome and asthma",
    "external_sample_id": null,
    "library_type": "Targeted/16S",
    "location_lat": 39.9525839,
    "location_lon": -75.1652215,
    "location_string": "Philadelphia, PA, USA",
    "name": null,
    "platform": "Illumina HiSeq",
    "sample": {
        "$ref": "/api/v1/samples/05631a0d9b084c43"
    },
    "sample_type": "Metagenomic",
    "starred": false
}

Path Params

id
string
required

Sample ID

 

GET a single metadata record by its ID.

Suggest Edits

Retrieve All Tags

 
gethttps://app.onecodex.com/api/v1/tags
curl https://app.onecodex.com/api/v1/tags -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/tags where=="{'name': {'$startswith': 'ST'}"
ocx.Tags.all()

#  [<Tags 34f07d39e83c4e0c: "unknown">,
#  <Tags 2ed3130dcca34221: "microbiome">,
#  <Tags d8b016fa492745b2: "raw reads">,
#  <Tags 038a303ad9084f52: "stool">,
# ...]
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
    {
        "$uri": "/api/v1/tags/0eab1dda4dfb4847",
        "name": "ST–1647"
    },
    {
        "$uri": "/api/v1/tags/5a385995cf25459a",
        "name": "ST–11"
    },
    ...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all tags. Returns a paginated list of tags.

Suggest Edits

Retrieve A Tag

 
gethttps://app.onecodex.com/api/v1/tags/<id>
curl https://app.onecodex.com/api/v1/tags/0eab1dda4dfb4847 -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/tags/0eab1dda4dfb4847 
ocx.Tags.get('0eab1dda4dfb4847')

# Returns <Tags 0eab1dda4dfb4847: "ST–1647">
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/tags/0eab1dda4dfb4847",
    "name": "ST–1647"
}

Path Params

id
string
required

Sample ID

 

GET a single tag by its ID.

Suggest Edits

Updating Metadata

 
patchhttps://app.onecodex.com/api/v1/metadata/<id>
curl -u $ONE_CODEX_API_KEY: -X PATCH -H "Content-Type: application/json" -d '{"pltaform": "Illumina MiSeq"}' https://app.onecodex.com/api/v1/metadata/8f869e3d72114ad1
# Update platform
http --auth $ONE_CODEX_API_KEY: PATCH https://app.onecodex.com/api/v1/metadata/8f869e3d72114ad1 platform="Illumina MiSeq"
metadata = ocx.Metadata.get('8f869e3d72114ad1')
metadata.platform = "Illumina MiSeq"
metadata.save()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/metadata/8f869e3d72114ad1",
    "custom": {},
    "date_collected": "2016-10-01T07:00:00+00:00",
    "date_sequenced": "2016-10-05T07:00:00+00:00",
    "description": "CHILD gut microbiome and asthma",
    "external_sample_id": null,
    "library_type": "Targeted/16S",
    "location_lat": 39.9525839,
    "location_lon": -75.1652215,
    "location_string": "Philadelphia, PA, USA",
    "name": null,
    "platform": "Illumina HiSeq",
    "sample": {
        "$ref": "/api/v1/samples/05631a0d9b084c43"
    },
    "sample_type": "Metagenomic",
    "starred": false
}

Path Params

id
string
required

Metadata record ID

Body Params

name
string

The optional sample name to display in the One Codex platform. The sample's filename is otherwise used.

description
string

An optional sample description

location_lat
float

The latitude (-90 – 90.0) of the sample location. By convention, we recommend using this for the location in which the physical specimen was collected.

location_lon
float

The longitude (-180.0 – 180.0) of the sample location.

location_string
string

A string describing the location. Currently, we do not attempt to automatically parse the lat/lon from these (). The One Codex web application does however set all 3 via a map.

platform
string

An enum with the name of the sequencing platform. Currently, the following values are valid: ["Illumina MiSeq", "Illumina HiSeq", "Illumina NextSeq 500", "Illumina Genome Analyzer II", "PacBio", "Oxford Nanopore MinION", "Ion Torrent", "Ion Proton", "SOLiD", "454 sequencing", "Sanger", null].

library_type
string

An enum with the sample type. This is currently limited to the following values: ["WGS", "Targeted/16S", "Other", null].

sample_type
string

An enum with the sample type. This is currently limited to the following values: ["Isolate", "Metagenomic", "Other", null].

date_collected
date

Timestamp for when the sample was collected.

date_sequenced
date

Timestamp for when the sample was sequenced.

external_sample_id
string

An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters.

starred
boolean

Whether the sample has been starred by the user within the One Codex web application.

custom
object

Arbitrary metadata is supported as part of a custom object. These have two constraints: (1) they must have a depth of one (i.e., no nested records); and (2) only strings, numbers, boolean, and null values are supported. Example: {"lab_tech": "Linus Pauling"}

 

Update the metadata record accompanying a sample. Users may only update the metadata for samples they own, or which are part of shared projects in which they have the relevant metadata editing permissions.

Suggest Edits

The Analysis Resource

 

The Analysis resource represents a reproducible analysis of an underlying sample using a strictly versioned analysis job.

Analysis types

The One Codex platform supports several types of analyses including metagenomic (or taxonomic) classification, in silico panels, and alignments. Additional analysis types are planned and will be added to the v1 API over time.

All user-viewable analyses are available via the /api/v1/analyses route, while the /api/v1/classifications, /api/v1/panels, and /api/v1/alignments routes provide listings of a subset of the same analyses with the relevant type. These specific resources provide more detailed information and additional routes, but represent the same underlying execution of a job against a sample.

Analysis resource properties

The below table summarizes all of the properties for the Analysis resource, with the JSON schema type of each property listed below in italics.

Property
Description

$uri
string

The analysis ID encoded as an addressable URI

analysis_type
string

The type of analysis performed. Currently supported analysis types on the One Codex platform are: classification, panel, and alignment.

created_at
date-time

Timestamp for when the analysis was created on the One Codex platform, encoded as a RFC 3339 timestamp

complete
boolean

If the analysis is complete. Incomplete or pending analyses will show a icon in the One Codex web application.

success
boolean

true if the analysis was successful.

error_msg
string

An error message if the analysis failed. Should generally be "" or null if the analysis succeeded or is pending.

job
string

A reference to the versioned job underlying the analysis, e.g., {"$ref": "/api/v1/jobs/d512cb556241440f"}.

sample
string

A reference to the sample underlying the analysis, e.g., {"$ref": "/api/v1/sample/0ee172af60e84f61"}

Suggest Edits

Retrieve All Analyses

 
gethttps://app.onecodex.com/api/v1/analyses
curl https://app.onecodex.com/api/v1/analyses -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/analyses sort=="{'success': true}"
onecodex analyses
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

ocx.Analyses.all()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
  	  "$uri": "/api/v1/analyses/e18dc42b4f0d427b",
	    "analysis_type": "classification",
	    "complete": true,
	    "created_at": "2016-04-18T00:24:47.469033+00:00",
	    "error_msg": "",
	    "job": {
	        "$ref": "/api/v1/jobs/dd71422220c3423b"
	    },
	    "sample": {
	        "$ref": "/api/v1/samples/0ee172af60e84f61"
	    },
	    "success": true
	},
  ...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all Analyses instances. Returns a paginated list of Analyses.

Suggest Edits

Retrieve An Analysis

 
gethttps://app.onecodex.com/api/v1/analyses/<id>
curl https://app.onecodex.com/api/v1/analyses/e18dc42b4f0d427b -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/analyses/e18dc42b4f0d427b
onecodex analyses e18dc42b4f0d427b
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

analysis = ocx.Analyses.get('e18dc42b4f0d427b')
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/analyses/e18dc42b4f0d427b",
    "analysis_type": "classification",
    "complete": true,
    "created_at": "2016-04-18T00:24:47.469033+00:00",
    "error_msg": "",
    "job": {
        "$ref": "/api/v1/jobs/dd71422220c3423b"
    },
    "sample": {
        "$ref": "/api/v1/samples/0ee172af60e84f61"
    },
    "success": true
}

Path Params

id
string
required

Analysis ID

 

GET a single analysis by its ID.

Suggest Edits

The Classification Resource

 

The Classification is an analysis providing metagenomic classification results for a sample. It has the same properties as an analyses (less the analysis_type field), and several additional routes that:

Property
Description

$uri
string

The analysis/classification ID encoded as an addressable URI

created_at
date-time

Timestamp for when the analysis was created on the One Codex platform, encoded as a RFC 3339 timestamp

complete
boolean

If the classification is complete. Incomplete or pending analyses will show a icon in the One Codex web application.

success
boolean

true if the classification was successful.

error_msg
string

An error message if the classification failed. Should generally be "" or null if the analysis succeeded or is pending.

job
string

A reference to the versioned job underlying the classification, e.g., {"$ref": "/api/v1/jobs/d512cb556241440f"}.

sample
string

A reference to the sample underlying the classification, e.g., {"$ref": "/api/v1/sample/0ee172af60e84f61"}

Suggest Edits

Retrieve All Classifications

 
gethttps://app.onecodex.com/api/v1/classifications
curl https://app.onecodex.com/api/v1/classifications -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/classifications sort=="{'success': true}"
onecodex classifications
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

ocx.Classifications.all()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
	{
    "$uri": "/api/v1/classifications/e18dc42b4f0d427b",
    "complete": true,
    "created_at": "2016-04-18T00:24:47.469033+00:00",
    "error_msg": "",
    "job": {
        "$ref": "/api/v1/jobs/dd71422220c3423b"
    },
    "sample": {
        "$ref": "/api/v1/samples/0ee172af60e84f61"
    },
    "success": true
	}
  ...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all Classification instances. Returns a paginated list of Classifications.

Suggest Edits

Retrieve A Classification

 
gethttps://app.onecodex.com/api/v1/classifications/<id>
curl https://app.onecodex.com/api/v1/classifications/e18dc42b4f0d427b -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/classifications/e18dc42b4f0d427b
onecodex classifications e18dc42b4f0d427b
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

classification = ocx.Classifications.get('e18dc42b4f0d427b')
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/classifications/e18dc42b4f0d427b",
    "complete": true,
    "created_at": "2016-04-18T00:24:47.469033+00:00",
    "error_msg": "",
    "job": {
        "$ref": "/api/v1/jobs/dd71422220c3423b"
    },
    "sample": {
        "$ref": "/api/v1/samples/0ee172af60e84f61"
    },
    "success": true
}

Path Params

id
string
required

Analysis ID – must be a classification type analysis or will return a 404

 

GET a single classification by its ID.

Suggest Edits

Classification Results

 
gethttps://app.onecodex.com/api/v1/classifications/<id>/results
curl https://app.onecodex.com/api/v1/classifications/e18dc42b4f0d427b/results -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/classifications/e18dc42b4f0d427b/results
onecodex classifications e18dc42b4f0d427b --results
classification = ocx.Classifications.get('e18dc42b4f0d427b')
classification.results()   # Return the raw JSON results
classification.table()     # Return the JSON as a Pandas DataFrame
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "n_reads": 139264,
    "host_tax_ids": ["9606"],
    "table": [
        {
            "abundance": null,
            "name": "Prevotella sp. 10(H)",
            "parent_tax_id": "838",
            "rank": "species",
            "readcount": 14,
            "readcount_w_children": 14,
            "tax_id": "1158294"
        },
        {
            "abundance": null,
            "name": "Tissierellia bacterium S7-1-4",
            "parent_tax_id": "1737408",
            "rank": "species",
            "readcount": 5,
            "readcount_w_children": 5,
            "tax_id": "1284708"
        },
				...
    ]
}

Path Params

id
string
required

Analysis ID – must be a classification type analysis or will return a 404

 

Return the results of a classification as JSON.

The returned JSON has the following top-level structure:

Property
Description

n_reads
integer

The total number of reads (or FASTA contigs/records) in sample.

host_tax_ids
array of strings

An array of the taxonomy ID for all known hosts in the sample. Filtering out the host_tax_ids and any non-unique mappings (e.g., those to "root" and "cellular organisms") can be used to produce a table of exclusively microbial taxa.

table
object

The results in a tabular format. Results will typically be sorted by readcount_w_children (descending). See below for more details.

The table object has the results for all taxa in the sample and the following fields:

Property
Description

tax_id
string

A taxonomy ID. Currently, these are NCBI taxonomy IDs and strictly versioned as part of the job. tax_id should be handled as a string in part to support future compatibility with non-NCBI taxonomies.

name
string

The name of the taxon. This is provided strictly for convenience and names for a given taxa are not guaranteed to remain identical over time. Use tax_id when comparing equality across different taxa.

rank
string

The taxonomic rank. This is also provided for convenience and guaranteed to be consistent for a given job but may change over time as, e.g., previously poorly characterized organisms are better characterized and taxonomically re-labeled.

parent_tax_id
string

The immediate parent of the taxon. Guaranteed to be consistent for all classifications using a given job.

readcount
integer

The number of reads (or records or contigs for FASTA files) classified at the given taxon.

readcount_w_children
integer

The number of reads classified at the given taxon and all of its children. E.g., if 50 reads map to Enterobacteriaceae in a sample and 50 reads map to E. coli, readcount would be 50 for Enterobacteriaceae and readcount_w_children would be 100.

abundance
number

An estimated relative microbial abundance for the organism. Currently, this will only be provided for classifications using the One Codex database and will only include estimates at the species level (example). Where available, this field should provide substantially improved relative abundance estimate over read-based summaries. See our announcement on this functionality for more detail: http://blog.onecodex.com/2016/04/25/2-0/

Note on future changes (): We do likely plan to add additional top-level fields to the returned JSON, e.g., whether the analysis contains abundance estimates or other similar metrics and descriptive features. We do not anticipate removing any top-level fields or fields in the table of results provided.

Suggest Edits

Read-Level Results

 
gethttps://app.onecodex.com/api/v1/classifications/<id>/readlevel
curl https://app.onecodex.com/api/v1/classifications/e18dc42b4f0d427b/readlevel -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/classifications/e18dc42b4f0d427b/readlevel
onecodex classifications e18dc42b4f0d427b --raw
# Not currently supported, use the HTTP REST API directly
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "url": "https://a-presigned-url-for-downloading-the-tsv.onecodex.com",
}

Path Params

id
string
required

Analysis ID – must be a classification type analysis or will return a 404

 

Return a URL with which the read-level results for the classification may be downloaded. Note that the CLI automatically downloads the read-level results TSV file when using the --raw flag. The read-level results may be downloaded in the One Codex web application on the righthand side of each analysis page:

The resulting gzipped TSV file will typically have the following columns (note that these are the standard fields for One Codex Database results but are not guaranteed to be stable and may differ for, e.g., different underlying databases and classifiers):

Property
Description

Header
string

The FASTA or FASTQ header for the record. In practice these should match the input order of the FASTA/Q file, though this is not strictly guaranteed. This column exists for all results.

Tax ID
string

The taxonomy ID the read is assigned to. Note that this is a read-level assignment that does not incorporate global sample-wide information. This column exists for all results.

N Hits
int

The number of k-mers found in the input read against the target database. This column exists for all k-mer based classification results.

Seq Len
int

The length of the read or contig. This column exists for all results.

Passed Filter
boolean/string

Whether the read passed a sample-wide filter. T indicates True and F indicates False. Reads not passing the filter may be erroneously assigned based on adapters, stacking artifacts, and other errors and should generally be ignored. This column exists for any results where global, sample-wide filtering is applied. All One Codex database results since April 2016 have included this field (details).

Kmer Chain

string

A sequence of :-separated taxonomy IDs (tax_id) and position (pos) pairs (e.g., 543:10) indicating the starting positions of all contiguous series of hits within the input read. Transitions between different taxonomy IDs are separated with a |.

The sample string 543:1|562:22|0:25, indicates that all of the k-mers beginning at position 1 through 21 map to the NCBI taxonomy ID 543 (Enterobacteriaceae), all k-mers beginning at position 22 through position 24 map to 562 (E. coli), and the k-mers beginning at position 25 through the end of the input read have no hits.

This column exists for all current k-mer based classification results, but will likely be discontinued in 2017. Note: The special value 0 is used to indicate no hit. 1 represents the root of the taxonomic tree.

Suggest Edits

The Panel Resource

 

The Panel is an analysis providing results for a set of marker sequences, which can range from very short sequences (e.g., 30-50 bases) to complete genes. These marker sequences are typically either predictive of function (e.g., antimicrobial resistance, virulence) or useful for typing (e.g., indicative of serotype or strain information). A panel has the same properties as an analyses (less the analysis_type field), and several additional routes that:

Property
Description

$uri
string

The analysis/panel ID encoded as an addressable URI

created_at
date-time

Timestamp for when the analysis was created on the One Codex platform, encoded as a RFC 3339 timestamp

complete
boolean

If the panel is complete. Incomplete or pending analyses will show a icon in the One Codex web application.

success
boolean

true if the panel analysis was successful.

error_msg
string

An error message if the classification failed. Should generally be "" or null if the analysis succeeded or is pending.

job
string

A reference to the versioned job underlying the panel, e.g., {"$ref": "/api/v1/jobs/4470c9beeb314d77"}.

sample
string

A reference to the sample underlying the panel, e.g., {"$ref": "/api/v1/sample/6d5247665454405a"}

Suggest Edits

Retrieve A Panel

 
gethttps://app.onecodex.com/api/v1/panels/<id>
curl https://app.onecodex.com/api/v1/panels/8ab1afc2c6e94100 -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/panels/8ab1afc2c6e94100
onecodex panels 8ab1afc2c6e94100
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

panel = ocx.Panels.get('8ab1afc2c6e94100')
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "$uri": "/api/v1/panels/8ab1afc2c6e94100",
  "complete": true,
  "created_at": "2016-09-27T21:26:56.966863+00:00",
  "error_msg": "",
  "job": {
    "$ref": "/api/v1/jobs/4470c9beeb314d77"
  },
  "sample": {
    "$ref": "/api/v1/samples/6d5247665454405a"
  },
  "success": true
}

Path Params

id
string
required

Analysis ID – must be a panel type analysis or will return a 404

 

GET a single panel by its ID.

Suggest Edits

Retrieve All Panels

 
gethttps://app.onecodex.com/api/v1/panels
curl https://app.onecodex.com/api/v1/panels -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/panels sort=="{'success': true}"
onecodex panels
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

ocx.Panels.all()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "$uri": "/api/v1/panels/8ab1afc2c6e94100",
    "complete": true,
    "created_at": "2016-09-27T21:26:56.966863+00:00",
    "error_msg": "",
    "job": {
      "$ref": "/api/v1/jobs/4470c9beeb314d77"
    },
    "sample": {
      "$ref": "/api/v1/samples/6d5247665454405a"
    },
    "success": true
  },
  ...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all Panel instances. Returns a paginated list of Panels.

Suggest Edits

Panel Results

 
gethttps://app.onecodex.com/api/v1/panels/<id>/results
curl https://app.onecodex.com/api/v1/panels/8ab1afc2c6e94100/results -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/panels/8ab1afc2c6e94100/results
onecodex panels 8ab1afc2c6e94100 --results
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

panel = ocx.Panels.get('8ab1afc2c6e94100')
panel.results()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "$uri": "/api/v1/panels/8ab1afc2c6e94100",
  "complete": true,
  "created_at": "2016-09-27T21:26:56.966863+00:00",
  "error_msg": "",
  "job": {
    "$ref": "/api/v1/jobs/4470c9beeb314d77"
  },
  "sample": {
    "$ref": "/api/v1/samples/6d5247665454405a"
  },
  "success": true
}

Path Params

id
string
required

Analysis ID – must be a panel type analysis or will return a 404

 

Return the results of a panel as JSON.

The returned JSON has the following top-level structure:

Property
Description

panel_name
string

The name of the panel, e.g,. "Antibiotic Resistance Determinants" for the ARDM panel.

panel_results
object

An object consisting of 1 or more "sub-panels", which then include the individual results for the markers (format below).

The panel_results object itself contains 1 or more sub-panels which consist of a description entry and then a list of markers. The markers themselves contain the following fields. Note that currently panels can consist of short and/or long markers, for which slightly different fields may be reported:

Property
Description

name
string

The name of the marker sequence.

description
string

A description of the marker.

status
string

Whether the marker sequence is 'present', 'probable', or 'absent'. This determination is based on the below fields, but cutoff values may differ between panels.

The default thresholds are as following: (1) for long markers identity and coverage >= 99% for "present" and >= 95% for "probable"; (2) for short markers the presence of an exact match is required for a "present" call and a partial match (<= 3 SNPs) is required for a "probable" call.

length
integer

The length of the marker sequence.

identity
number

The percent identity of the detected marker sequence in the sample. Provided only for "long" marker sequences (e.g., genes).

coverage
number

The coverage of the detected marker sequence in the sample. Provided only for "long" marker sequences (e.g., genes).

depth
number

The depth of coverage for the detected marker sequence in the sample. Provided only for "long" marker sequences (e.g., genes).

n_reads_exact_match
integer

The number of reads including an exact match to the marker sequence. Provided only for "short" marker sequences (e.g., <= ~50 bp).

n_reads_partial_match
integer

The number of reads including an partial match to the marker sequence. By default, a partial match is defined as being within 3 SNPs of the exact sequence. Provided only for "short" marker sequences (e.g., <= ~50 bp).

Warning – Experimental Route (): The above JSON format is not guaranteed to remain stable, though we do not expect to substantively alter the meaning of any fields. Please use caution and include fallbacks when writing non-exploratory code using the above route. Please also feel free to reach out if you'd like to discuss this format and any forthcoming changes with us.

Suggest Edits

The Alignment Resource

 

An Alignment is an analysis providing sensitive local alignment of a WGS samples against a specific reference genome sample. It has the same properties as an analyses, but lacks the analysis_type field and also includes a tax_id field indicating what .

At this time, there are no v1 API routes for accessing the alignment statistics (e.g., percent identity, coverage, and depth), but alignments can be viewed on the One Codex platform directly. Here's an example public alignment and a list of all alignments for that sample:

Property
Description

$uri
string

The analysis/alignment ID encoded as an addressable URI

created_at
date-time

Timestamp for when the analysis was created on the One Codex platform, encoded as a RFC 3339 timestamp

complete
boolean

If the alignment is complete. Incomplete or pending analyses will show a icon in the One Codex web application.

success
boolean

true if the alignment was successful.

error_msg
string

An error message if the alignment failed. Should generally be "" or null if the analysis succeeded or is pending.

job
string

A reference to the versioned job underlying the alignment, e.g., {"$ref": "/api/v1/jobs/d512cb556241440f"}.

sample
string

A reference to the sample underlying the alignment, e.g., {"$ref": "/api/v1/sample/0ee172af60e84f61"}

tax_id
string

The taxonomy ID used in determining which reference to align against. Taxonomy IDs are NCBI IDs encoded as strings, and may be species or sub-species level. Alignments will use the best available reference genome available.

Suggest Edits

Retrieve All Alignments

 
gethttps://app.onecodex.com/api/v1/alignments
curl https://app.onecodex.com/api/v1/alignments -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/alignments sort=="{'success': true}"
# Not currently supported as a command line option, use the Python client library instead
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

ocx.Alignments.all()
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
    "$uri": "/api/v1/alignments/1aefe494c50d4260",
    "complete": true,
    "created_at": "2016-10-27T19:06:35.807811+00:00",
    "error_msg": "",
    "job": {
      "$ref": "/api/v1/jobs/9829be9f5eca4d66"
    },
    "sample": {
      "$ref": "/api/v1/samples/6d5247665454405a"
    },
    "success": true,
    "tax_id": "1262962"
  },
  ...
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all Alignment instances. Returns a paginated list of Alignments.

Suggest Edits

Retrieve An Alignment

 
gethttps://app.onecodex.com/api/v1/alignments/<id>
curl https://app.onecodex.com/api/v1/alignments/1aefe494c50d4260 -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/alignments/1aefe494c50d4260
# Not currently supported as a command line option, use the Python client library instead
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY)

classification = ocx.Alignments.get('1aefe494c50d4260')
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
  "$uri": "/api/v1/alignments/1aefe494c50d4260",
  "complete": true,
  "created_at": "2016-10-27T19:06:35.807811+00:00",
  "error_msg": "",
  "job": {
    "$ref": "/api/v1/jobs/9829be9f5eca4d66"
  },
  "sample": {
    "$ref": "/api/v1/samples/6d5247665454405a"
  },
  "success": true,
  "tax_id": "1262962"
}

Path Params

id
string
required

Analysis ID – must be a alignment type analysis or will return a 404

 

GET a single alignment by its ID.

Suggest Edits

The Job Resource

 

A Job represents a versioned analysis pipeline and is designed to provide strict reproducibility guarantees. In practice, a job encompasses the following strictly versioned components:

  • Reference data
  • Analysis code
  • The execution environment itself (e.g., a Linux container)

All analyses on One Codex are backed by a job that runs on our reproducible analysis infrastructure.

The below table summarizes all of the properties for the Job resource, with the JSON schema type of each property listed below in italics.

Property
Description

$uri
string

The job ID encoded as an addressable URI

analysis_type
string

The type of analysis. See the analysis resource properties] for more details.

created_at
date-time

Timestamp for when the job was created on the One Codex platform, encoded as a RFC 3339 timestamp

name
string

The name of the job (this is displayed in the dropdown on the analysis page of the One Codex web application).

public
boolean

Whether the job is publicly available. For most jobs this will be true. Custom, private jobs are also available, and will only be visible to users whose samples (or samples shared with them) have been analyzed using that job.

Note on future changes (): We plan to expose additional top-level fields for jobs, such as whether they can be launched by the user (i.e., are they user_runnable?) and any associated costs. In the meantime, all available user-runnable jobs, and their associated costs, may be found within the One Codex web application on the Run Analyses page: https://app.onecodex.com/jobs

Suggest Edits

Retrieve All Jobs

 
gethttps://app.onecodex.com/api/v1/jobs
curl https://app.onecodex.com/api/v1/jobs -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/jobs sort=="{'created_at': true}"
# Not currently supported as a command line option, use the Python client library instead
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY")

# Retrieve all jobs
samples = ocx.Jobs.all()

# Retrieve all "classification" jobs
classification_jobs = ocx.Jobs.where(analysis_type='classification')
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
[
  {
      "$uri": "/api/v1/jobs/ea2ef469ebc4454f",
      "analysis_type": "classification",
      "created_at": "2016-05-05T17:26:02.116480+00:00",
      "name": "One Codex Database",
      "public": true
  },
  {
      "$uri": "/api/v1/jobs/f7fdd82f8d994e25",
      "analysis_type": "classification",
      "created_at": "2016-05-03T22:34:26.695848+00:00",
      "name": "Targeted Loci (Preview - Summer '16)",
      "public": false
  },
  {
      "$uri": "/api/v1/jobs/52c73e0c9a4d4b3f",
      "analysis_type": "classification",
      "created_at": "2015-11-02T00:25:34.905432+00:00",
      "name": "RefSeq Complete Genomes",
      "public": true
  },
  {
      "$uri": "/api/v1/jobs/d512cb556241440f",
      "analysis_type": "classification",
      "created_at": "2015-11-02T00:24:48.185683+00:00",
      "name": "One Codex Database (Fall 2015)",
      "public": true
  }
]

Query Params

where
string

Optional Mongo-style JSON filter clause, e.g., where={"$uri": {"$eq": "/api/v1/samples/0ee172af60e84f61"}}

sort
string

Optional Mongo-style JSON sort clause, e.g., sort={"created_at": true} to sort by created_at (descending)

page
int32

Page number. Defaults to 1. See Pagination for more details.

per_page
int32

Number of requested paginated records. Defaults to 50. See Pagination for more details.

 

GET all Jobs instances. Returns a paginated list of Jobs.

Suggest Edits

Retrieve A Job

 
gethttps://app.onecodex.com/api/v1/jobs/<id>
curl https://app.onecodex.com/api/v1/job/ea2ef469ebc4454f -u $ONE_CODEX_API_KEY:
http --auth $ONE_CODEX_API_KEY https://app.onecodex.com/api/v1/jobs/ea2ef469ebc4454f
# Not currently supported as a command line option, use the Python client library instead
from onecodex import Api
ocx = Api(api_key="YOUR_API_KEY")

# Retrieve Job ea2ef469ebc4454f
job = ocx.Jobs.get('ea2ef469ebc4454f')

# Retrieve analyses using that job
analyses = ocx.Analyses.where(job=job)
Status: {{ results.statusCode[0] }}
{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
     200 OK
{
    "$uri": "/api/v1/jobs/ea2ef469ebc4454f",
    "analysis_type": "classification",
    "created_at": "2016-05-05T17:26:02.116480+00:00",
    "name": "One Codex Database",
    "public": true
}

Path Params

id
string
required

Job ID

 

GET a single job by its ID.