# The Account Resource
Source: https://developer.onecodex.com/api-reference/account-resource
The `account` resource exposes information about the currently authenticated user's account — their associated user record, email, and account confirmation timestamp. This is the singleton endpoint you call to identify which user an API key belongs to.
# Retrieve The Authenticated Account
Source: https://developer.onecodex.com/api-reference/account-resource-get
GET /api/v1/account
GET the Account associated with the authenticated API key.
# The Alignment Resource
Source: https://developer.onecodex.com/api-reference/alignment-resource
An Alignment is an [analysis](/api-reference/analysis-resource) 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 the taxonmic ID of the genome against which the alignment was performed.
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](https://app.onecodex.com/alignment/public/1aefe494c50d4260) and a list of [all alignments for that sample](https://app.onecodex.com/analysis/6d5247665454405a/alignments):
![]()
# Retrieve An Alignment
Source: https://developer.onecodex.com/api-reference/alignment-resource-get
GET /api/v1/alignments/{id}
GET a single alignment by its ID.
# Retrieve All Alignments
Source: https://developer.onecodex.com/api-reference/alignment-resource-instances
GET /api/v1/alignments
GET all Alignment instances. Returns a paginated list of Alignments.
# The Analysis Resource
Source: https://developer.onecodex.com/api-reference/analysis-resource
The Analysis resource represents a reproducible analysis of an underlying [sample](/api-reference/sample-resource) using a strictly versioned [analysis job](/api-reference/job-resource).
## 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.
# Retrieve Analysis Output File Details
Source: https://developer.onecodex.com/api-reference/analysis-resource-file-details
GET /api/v1/analyses/{id}/file_details
GET the list of files produced by an analysis in JSON format, along with their sizes and pre-signed URLs.
# Retrieve An Analysis
Source: https://developer.onecodex.com/api-reference/analysis-resource-get
GET /api/v1/analyses/{id}
GET a single analysis by its ID.
# Retrieve All Analyses
Source: https://developer.onecodex.com/api-reference/analysis-resource-instances
GET /api/v1/analyses
GET all Analyses instances. Returns a paginated list of Analyses.
# Retrieve Analysis Results
Source: https://developer.onecodex.com/api-reference/analysis-resource-results
GET /api/v1/analyses/{id}/results
GET the results of an analysis in JSON format. Note that there is no fixed response schema, and analyses that do not have JSON results (or which cannot be fetched) will return a 404. We strongly recommend using the [Classification Results](/api-reference/classification-resource-results), [Panel Results](/api-reference/panel-resource-results), or [Alignment Results](/api-reference/alignment-resource-results) directly where applicable.
# API Documentation
Source: https://developer.onecodex.com/api-reference/api-documentation
The below sections provide more exhaustive documentation of the core One Codex API, but first a note and a warning:
Our API is self-described using [JSON Schema](http://json-schema.org/), with the root schema for the API available at [https://app.onecodex.com/api/v1/schema](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](mailto:support@onecodex.com) or contacting us via the chat icon on the bottom right. Thanks!
# Authentication
Source: https://developer.onecodex.com/api-reference/authentication
Getting started with secure access to the One Codex API
The One Codex API supports two methods of authentication. Only secure connections (HTTPS) are allowed.
### HTTP Basic Auth
Use your API key as the username and an empty password:
```shell curl theme={null}
curl https://app.onecodex.com/api/v1/schema -u $ONE_CODEX_API_KEY:
```
```shell httpie theme={null}
http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/schema
```
### API Key Header
Alternatively, you can pass your API key in the `X-API-Key` header:
```shell curl theme={null}
curl https://app.onecodex.com/api/v1/schema -H "X-API-Key: $ONE_CODEX_API_KEY"
```
```shell httpie theme={null}
http https://app.onecodex.com/api/v1/schema X-API-Key:$ONE_CODEX_API_KEY
```
Both methods are equivalent. The API key header approach is what the API playground examples on this site use.
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](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.
```json json theme={null}
{
"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
}
```
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](https://app.onecodex.com/settings) pane of the One Codex web application. This will automatically revoke your old key.
Our API servers also support [JWT](https://jwt.io/)-based authentication, which offer different security and usability tradeoffs. We plan to make JWT token generation available via the [Settings](https://app.onecodex.com/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:
![488]()
Within the [Settings](https://app.onecodex.com/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!
![1726]()
## 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](https://app.onecodex.com/settings) page:
![1716]()
**Please note:** You will need to update any code, configuration files, or environmental variables using the key.
# Checking Signatures
Source: https://developer.onecodex.com/api-reference/checking-webhook-signatures
In a production setting, it is important to verify signatures sent as part of the webhook payloads. Verifying these signatures ensures that the payloads were sent by One Codex and not a malicious third party.
In addition to the webhook payload body, we include a custom `X-OneCodex-Signature` HTTP header with all delivered webhooks. These signatures are generated using a hash-based message authentication code (HMAC) with SHA-256. Here's an example header:
```
X-OneCodex-Signature: t=1492774577c v1=d929ba98ac0e56ff425f9b8ed7c7ab631dc680f9ea80ce2f604cc75580a63b53
```
Where `t=` provides a Unix timestamp and `v1=` provides the v1 signature (currently the only signature scheme). The signature uses a webhook secret (defaults to the API key for your account) to sign the POST payload body and timestamp. To verify the signature of the payload, you need to:
1. Extract the timestamp and signature from the headers
2. Concatenate the the timestamp and request payload with a `.` to generate a signed payload
3. Determine the expected signature; and finally
4. Verify that the expected signature matches the received signature
Some brief Python 3 code for validating the signature is included for demonstration purposes below:
```python python theme={null}
import hashlib
import hmac
import json
from flask import request
# Parse the request using your web framework of choice.
# Note that the entire body of the request is the payload
# and that you may need to parse the raw request body
# vs. any loaded JSON in a different language or framework
# (this code assumes a Python Flask request object).
payload = request.json
header = request.headers.get("X-OneCodex-Signature")
# 1. Extract the timestamp and signature
timestamp_part = header.split(" ")[0]
signature_part = header.split(" ")[1]
if not timestamp_part.startswith("t=") or not signature_part.startswith("v1="):
raise Exception("Bad signature header format")
timestamp = int(timestamp_part.split("=")[1])
signature = signature_part.split("=")[1]
# 2. Generate a concatenated signed payload
signed_payload = "%d.%s" % (timestamp, payload)
# 3. Compute the SHA256 hash of your secret
secret = hashlib.sha256("YOUR_WEBHOOK_SECRET".encode("utf-8")).hexdigest().encode("utf-8")
# 4. Determine the expected signature
expected_signature = hmac.new(
secret,
signed_payload.encode(),
digestmod=hashlib.sha256
).hexdigest()
# 4. Verify that the expected signature matches
assert expected_signature == signature
```
*Note: We use a similar format to [Stripe](https://stripe.com/docs/webhooks/signatures) for our payload signatures (they're the same except Stripe delimits the signed payload and timestamp with a comma vs. a space). See their [rich documentation](https://stripe.com/docs/webhooks/signatures) for additional details on why payload signatures are important and related webhook best practices.*
In the near future, we plan to add support for parsing `Event` objects and verifying the signatures from a webhook payload in our [onecodex](https://github.com/onecodex/onecodex) Python library. This will offer an easy, one line mechanism for verifying payload POST bodies sent by our platform.
# The Classification Resource
Source: https://developer.onecodex.com/api-reference/classification-resource
The Classification is an [analysis](/api-reference/analysis-resource) providing metagenomic classification results for a sample. It has the same properties as an analyses (less the `analysis_type` field), and includes routes for retrieving the [sample-level JSON classification results](/api-reference/classification-resource-results) as well as [read-level results](/api-reference/classification-resource-read-level).
# Retrieve A Classification
Source: https://developer.onecodex.com/api-reference/classification-resource-get
GET /api/v1/classifications/{id}
GET a single classification by its ID.
# Retrieve All Classifications
Source: https://developer.onecodex.com/api-reference/classification-resource-instances
GET /api/v1/classifications
GET all Classification instances. Returns a paginated list of Classifications.
# Read-Level Results
Source: https://developer.onecodex.com/api-reference/classification-resource-read-level
GET /api/v1/classifications/{id}/readlevel
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 `--read-level` 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. **Important Note:** This column exists for all analyses run before June 2017 but is discontinued in current and future analyses. We strongly recommend that any code indexing a results TSV uses the column headers to determine the position of relevant data rather than assuming a given column order and position. |
| **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](https://blog.onecodex.com/2016/04/25/2-0/)). |
| **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 `\|`. **Example:** 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. *Note: This column exists for all analyses run before June 2017 but is discontinued in current and future analyses. Note: The special value 0 is used to indicate no hit. 1 represents the root of the taxonomic tree.* |
# Retrieve Classification Results
Source: https://developer.onecodex.com/api-reference/classification-resource-results
GET /api/v1/classifications/{id}/results
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](https:///ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi) 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](https://app.onecodex.com/classification/sample)). Where available, this field should provide substantially improved relative abundance estimates over read-based summaries. See [our announcement on relative abundance](https://blog.onecodex.com/2016/04/25/2-0/) for more detail on this functionality. |
| **abundance\_w\_children** *number* | An estimated, cumulative relative microbial abundance of all of the children of a given taxon. E.g., the `abundance_w_children` for *Escherichia* is the sum of the abundances for all species in the *Escherichia* genus. |
**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.
# CLI & Client Library (Python)
Source: https://developer.onecodex.com/api-reference/command-line-interface
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
* Automatic detection and interleaving of paired end (`*_R1`, `*_R2`) data
* Support for multiple simultaneous file uploads
* Microbiome data analysis, visualization and statistical functions
The command line interface is written in Python and accompanies our [client library](https://github.com/onecodex/onecodex). It should be easily installable on most machines with the following command:
```bash bash theme={null}
pip install onecodex # Note, Windows users may need to do `py -m pip install onecodex`
```
Documentation for the CLI and accompanying `onecodex` Python client library can be found [here](https://onecodex.github.io/onecodex/).
# The Document Resource
Source: https://developer.onecodex.com/api-reference/document-resource
A Document is a file of any type that might be associated with a Sample or Analysis. Examples of such files include: FAST5 files form Oxford Nanopore, PDF reports generated by our notebook service, and Excel spreadsheets containing metadata.
Documents uploaded to One Codex are stored securely and can be shared with members of your organization. Uploading Documents requires two direct API calls: one to start the upload, and one to confirm that the upload succeeded. If you need to upload a compressed file *over* 20GB in size, please contact us for help at [support@onecodex.com](mailto:support@onecodex.com).
The below table summarizes all of the **properties** for the Document resource, with the JSON schema type of each property listed below in italics. Details on how to upload, modify, and retrieve Documents follow.
# Share A Document With A User
Source: https://developer.onecodex.com/api-reference/document-resource-add-user
POST /api/v1/documents/{id}/add_user
Grant another user download access to a Document. The caller must be the document's uploader (or have org-level admin permission). The added user appears in the document's `downloaders` list.
# Confirming an Upload
Source: https://developer.onecodex.com/api-reference/document-resource-confirm-upload
POST /api/v1/documents/confirm_upload
Confirms the upload. See [Starting an Upload](/api-reference/document-resource-upload) for more details on the full upload workflow.
# Delete A Document
Source: https://developer.onecodex.com/api-reference/document-resource-delete
DELETE /api/v1/documents/{id}
Delete a Document.
# Downloading Documents
Source: https://developer.onecodex.com/api-reference/document-resource-download
POST /api/v1/documents/{id}/download_uri
Retrieves a Document stored at One Codex. First `POST` to the `download_uri` endpoint for the individual document. Then download the provided pre-signed `download_uri` link within the provided link expiration timeframe.
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).
# Retrieve A Document
Source: https://developer.onecodex.com/api-reference/document-resource-get
GET /api/v1/documents/{id}
GET a single Document by its ID.
# Retrieve All Documents
Source: https://developer.onecodex.com/api-reference/document-resource-instances
GET /api/v1/documents
GET all Document instances. Returns a paginated list of Documents.
# Revoke A User's Document Access
Source: https://developer.onecodex.com/api-reference/document-resource-remove-user
POST /api/v1/documents/{id}/remove_user
Revoke a user's download access to a Document.
# Rename A Document
Source: https://developer.onecodex.com/api-reference/document-resource-rename
PATCH /api/v1/documents/{id}/rename
Change a Document's `filename`.
# Starting a Document Upload
Source: https://developer.onecodex.com/api-reference/document-resource-upload-file
POST /api/v1/documents/init_upload
Start an upload by `POST`ing the `filename` and `size` to `/documents/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.
### Performing the actual upload
A typical upload involves `POST`ing a sample up to 20GB 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](https://httpie.org) or Python requests is:
```sh httpie theme={null}
# Start the upload
# Start the upload
http --auth $ONE_CODEX_API_KEY: POST \
https://app.onecodex.com/api/v1/documents/init_upload \
filename=report.pdf size:=31337
# 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"
# },
# "document_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@report.pdf
# Returns a 201 response
# Confirm the upload (see below)
http --auth $ONE_CODEX_API_KEY: POST \
https://app.onecodex.com/api/v1/documents/confirm_upload \
sample_id="28459508592a481c"
```
```python Python theme={null}
import os
import requests
# Start the upload
resp = requests.post('https://app.onecodex.com/api/v1/documents/init_upload',
json={'filename': 'report.pdf',
'size': os.path.getsize('report.pdf')},
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('report.pdf')})
# Finally, confirm the upload (should return a 200)
requests.post('https://app.onecodex.com/api/v1/documents/confirm_upload',
json={'document_id': resp['document_id']},
auth=(os.getenv('ONE_CODEX_API_KEY'), ''))
```
# Errors
Source: https://developer.onecodex.com/api-reference/errors
The One Codex API communicates errors with [standard HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) 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
```text Codes theme={null}
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**
```json json theme={null}
{
"message": "The server could not verify that you are authorized to access the URL requested. You either supplied the wrong credentials...",
"status": 401
}
```
# Retrieve An Event
Source: https://developer.onecodex.com/api-reference/event-resource-get
GET /api/v1/events/{id}
Get a single event by its ID.
# Retrieve All Events
Source: https://developer.onecodex.com/api-reference/event-resource-instances
GET /api/v1/events
List all available events. Note that events are generated on-demand and only listed and available programmatically if a relevant webhook subscription exists. By default, up to 30 days of events are available via this route. If you need additional historic event records, please contact us at [support@onecodex.com](mailto:support@onecodex.com).
# The Functional Profile Resource
Source: https://developer.onecodex.com/api-reference/functional-profile-resource
The Functional Profile is an [analysis](/api-reference/analysis-resource) which provides results for identifying gene families and pathways, profiling gene function and organism-specific contributions to metabolic pathways, and measuring gene abundance. The functional analysis leverages the [classification resource](/api-reference/classification-resource) to associate functional groups with taxonomic information, providing results that can be used to understand the functional capabilities of a sample and which organisms contribute to those functions. A functional profile has the same properties as an analysis, as well as a route for [profile-specific results](/api-reference/functional-profile-resource-results).
# Functional Profile Filtered Results
Source: https://developer.onecodex.com/api-reference/functional-profile-resource-filtered-results
GET /api/v1/functional_profiles/{id}/filtered_results
Return filtered functional profile results as JSON. The returned JSON is similar in structure to the
results returned by the [functional profile results](/api-reference/functional-profile-resource-results)
route. However, this route returns a simplified and filtered version of the results, which only includes a
specified functional group, metric, and taxa stratification option. All ambiguous results, such as
unmapped or ungrouped entries, are filtered out.
| Property | Description |
| ----------------------- | ------------------------------------------------------------------------------ |
| **n\_mapped** *integer* | The number of reads that were successfully mapped to a gene family or pathway. |
| **n\_reads** *integer* | The number of reads present in the sample. |
| **table** *array* | An array of objects consisting of individual functional groups (format below). |
The `table` array contains results for a single functional group and metric, and also includes taxonomic information.
Each object in the array has the following fields:
| Property | Description |
| ------------------------ | -------------------------------------------------------------------- |
| **id** *string* | A group-specific unique ID, e.g., GO:0006096, PF16874, COG0148. |
| **name** *string* | The name of the function. |
| **value** *number* | Gene family or pathway abundance in the specified `metric`. |
| **taxon\_id** *string* | The NCBI taxonomy ID for the organism associated with this function. |
| **taxon\_name** *string* | The name of the organism. |
**Warning**: The above JSON format is specific to the current version of the functional analysis job. This format is stable and guaranteed to remain stable for this version of the job. However, future versions of the functional analysis job may alter the format or introduce new changes. Please use caution and include fallbacks when writing non-exploratory code using the above route. Please also feel free to [reach out](mailto:support@onecodex.com) if you'd like to discuss this format and any forthcoming changes with us.
# Retrieve A Functional Profile
Source: https://developer.onecodex.com/api-reference/functional-profile-resource-get
GET /api/v1/functional_profiles/{id}
GET a single functional profile by its ID.
# Retrieve All Functional Profiles
Source: https://developer.onecodex.com/api-reference/functional-profile-resource-instances
GET /api/v1/functional_profiles
GET all Functional Profile instances. Returns a paginated list of Functional Profiles.
# Functional Profile Results
Source: https://developer.onecodex.com/api-reference/functional-profile-resource-results
GET /api/v1/functional_profiles/{id}/results
Return functional profile results as JSON. The returned JSON has the following top-level structure:
| Property | Description |
| ----------------------- | ------------------------------------------------------------------------------ |
| **n\_mapped** *integer* | The number of reads that were successfully mapped to a gene family or pathway. |
| **n\_reads** *integer* | The number of reads present in the sample. |
| **table** *array* | An array of objects consisting of individual functional groups (format below). |
The `table` array contains results across all functional groups and gene families, as well as taxonomic
information.
Each object in the array has the following fields:
| Property | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **group\_name** *string* | The name of the functional group this result corresponds to. This will be one of the following: `pathways`, `metacyc`, `eggnog`, `go`, `ko`, `ec`, `pfam`, or `reaction`. |
| **id** *string* | A group-specific unique ID, e.g., GO:0006096, PF16874, COG0148. |
| **metric** *string* | The quantitative metric represented by the `value` field. This field will be one of the following values: `cpm` (counts per million), `rpk` (reads per kilobase), `abundance`, `complete_abundance`, or `coverage`. The `abundance`, `complete_abundance` and `coverage` metrics will *only* be present for pathway results, while `cpm` and `rpk` metrics are present for all other functional groups. |
| **name** *string* | The name of the function. |
| **taxa\_stratified** *boolean* | A boolean indicating whether or not this result is associated with a specific organism. |
| **taxon\_id** *string* | The NCBI taxonomy ID for the organism associated with this function. |
| **taxon\_name** *string* | The name of the organism. |
| **value** *number* | Gene family or pathway abundance in the unit specified by the `metric` field. |
**Warning**: The above JSON format is specific to the current version of the functional analysis job. This format is stable and guaranteed to remain stable for this version of the job. However, future versions of the functional analysis job may alter the format or introduce new changes. Please use caution and include fallbacks when writing non-exploratory code using the above route. Please also feel free to [reach out](mailto:support@onecodex.com) if you'd like to discuss this format and any forthcoming changes with us.
# Getting Started
Source: https://developer.onecodex.com/api-reference/getting-started
A quick overview of the key concepts underlying the One Codex API
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](https://app.onecodex.com) 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](http://blog.onecodex.com/2016/04/25/2-0/), start [new analyses such as *in silico* panels and alignments](http://blog.onecodex.com/2016/09/26/running-new-analyses-whole-genome-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](https://app.onecodex.com/analysis/sample)) to panels for anti-microbial resistance ([example](https://app.onecodex.com/markerpanel/sample2)). 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](http://json-schema.org/). We hope that this format combined with an interactive API browser makes exploring and getting started with our API easy.
![1317]()
You can access the API using `cURL`, an HTTP client library in your preferred language, our [Python client library](https://github.com/onecodex/onecodex), or our [command line client](https://github.com/onecodex/onecodex).
Finally, if you find any part of the docs to be outdated or unclear, please [drop us a note](mailto:support@onecodex.com) 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.
# The Job Resource
Source: https://developer.onecodex.com/api-reference/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](/api-reference/analysis-resource) 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.
# Create A Job
Source: https://developer.onecodex.com/api-reference/job-resource-create
POST /api/v1/jobs
Register a new Job. The request body specifies the job's name, analysis type, container image, arguments schema, and reference assets. After a job is created, you can run it against a sample via [Run A Job](/api-reference/job-resource-run).
# Job Details
Source: https://developer.onecodex.com/api-reference/job-resource-details
GET /api/v1/jobs/{id}/details
Fetch full details for a Job, including its container image, asset dependencies, parent-job dependencies, and the structured arguments schema rendered as field groups suitable for building a UI form. This endpoint is intended for Custom Workflows only.
# Retrieve A Job
Source: https://developer.onecodex.com/api-reference/job-resource-get
GET /api/v1/jobs/{id}
GET a single job by its ID.
# Retrieve All Jobs
Source: https://developer.onecodex.com/api-reference/job-resource-instances
GET /api/v1/jobs
GET all Jobs instances. Returns a paginated list of Jobs.
# Update A Job
Source: https://developer.onecodex.com/api-reference/job-resource-patch
PATCH /api/v1/jobs/{id}
Update the human-readable metadata of an existing Job — its description, visibility, asset dependencies, and so on.
# Run A Job
Source: https://developer.onecodex.com/api-reference/job-resource-run
POST /api/v1/jobs/{id}/run
Trigger a Job against a sample (or another input), creating a new Analysis. The request body specifies the input sample, any required arguments, and an optional list of dependency analyses whose outputs should feed into this run. The response is the newly-created Analysis (or analysis subclass — Classification, Functional Profile, etc. — depending on the job's `analysis_type`).
# Jupyter Notebooks
Source: https://developer.onecodex.com/api-reference/jupyter-notebooks
We're also happy to offer embedded [Jupyter](https://jupyter.org) 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](http://blog.onecodex.com/2016/11/10/notebooks-and-more/) announcing notebooks, take a look at an [example notebook](https://app.onecodex.com/notebooks/public/0f5fe71670974b9a) that uses the [One Codex Python client library](https://github.com/onecodex/onecodex), or view our [more detailed notebook documentation](https://docs.onecodex.com/en/articles/3754220-custom-analysis-with-jupyter-notebooks).
![2612]()
# The Metadata Resource
Source: https://developer.onecodex.com/api-reference/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:
![]()
Metadata include the following **properties**:
# Retrieve A Metadata Record
Source: https://developer.onecodex.com/api-reference/metadata-resource-get
GET /api/v1/metadata/{id}
GET a single metadata record by its ID.
# Retrieve All Metadata
Source: https://developer.onecodex.com/api-reference/metadata-resource-instances
GET /api/v1/metadata
GET all metadata records. Returns a paginated list of Metadata records.
# Updating Metadata
Source: https://developer.onecodex.com/api-reference/metadata-resource-patch
PATCH /api/v1/metadata/{id}
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.
# The MLST Resource
Source: https://developer.onecodex.com/api-reference/mlst-resource
An MLST result is a multilocus sequence typing analysis — a specialized [analysis](/api-reference/analysis-resource) that identifies the sequence type (ST) of an isolate by typing housekeeping loci against a curated MLST scheme. MLST results are produced by jobs whose `analysis_type` is `mlst`.
The below table summarizes all of the **properties** for the MLST resource, with the JSON schema type of each property listed below in italics.
# Retrieve An MLST Result
Source: https://developer.onecodex.com/api-reference/mlst-resource-get
GET /api/v1/mlsts/{id}
GET a single MLST result by its ID.
# Retrieve All MLST Results
Source: https://developer.onecodex.com/api-reference/mlst-resource-instances
GET /api/v1/mlsts
GET all MLST analyses visible to the authenticated user. Returns a paginated list.
# MLST Results
Source: https://developer.onecodex.com/api-reference/mlst-resource-results
GET /api/v1/mlsts/{id}/results
GET the structured MLST result for a single analysis — the assigned sequence type (ST), the per-locus allele calls, and the MLST scheme used. The returned JSON has the following top-level structure:
| Property | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **panelResults** *object* | An object consisting of 1 or more "sub-panels", which include detailed alignment statistics (e.g., coverage, depth, etc.) for marker alleles used to determine sequence types (format below). |
| **mlstResults** *object* | An object containing sequence type information and detected alleles. |
The `panel_results` object itself contains 1 or more sub-panels which describe alignment statistics for all `markers`. Each marker is a separate allele that is used to determine a sequence type. The markers themselves contain the following fields.
| Property | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name** *string* | The name of the marker sequence, this includes the gene and allele number. |
| **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 identity and coverage `>= 99%` for "present" and `>= 95%` for "probable" |
| **length** *integer* | The length of the marker sequence. |
| **pct\_identity** *number* | The percent identity of the detected marker sequence in the sample. |
| **coverage** *number* | The breadth of coverage of the detected marker sequence in the sample. |
| **depth** *number* | The depth of coverage for the detected marker sequence in the sample. |
| **n\_reads** *integer* | The number of reads aligned to the marker sequence. |
**Warning**: 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](mailto:support@onecodex.com) if you'd like to discuss this format and any forthcoming changes with us.
# Pagination
Source: https://developer.onecodex.com/api-reference/pagination
The One Codex API follows the basic pagination model of the [GitHub API](https://developer.github.com/v3/#pagination). 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:
```text text theme={null}
HTTP/1.1 200 OK
Link: ; rel="self",
; rel="next"
; rel="last"
X-Total-Count: 46
```
# The Panel Resource
Source: https://developer.onecodex.com/api-reference/panel-resource
The Panel is an [analysis](/api-reference/analysis-resource) 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), as well as route for [panel-specific results](/api-reference/panel-resource-results).
# Retrieve A Panel
Source: https://developer.onecodex.com/api-reference/panel-resource-get
GET /api/v1/panels/{id}
GET a single panel by its ID.
# Retrieve All Panels
Source: https://developer.onecodex.com/api-reference/panel-resource-instances
GET /api/v1/panels
GET all Panel instances. Returns a paginated list of Panels.
# Panel Results
Source: https://developer.onecodex.com/api-reference/panel-resource-results
GET /api/v1/panels/{id}/results
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**: 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](mailto:support@onecodex.com) if you'd like to discuss this format and any forthcoming changes with us.
# The Project Resource
Source: https://developer.onecodex.com/api-reference/project-resource
Projects are a grouping mechanism for [samples](/api-reference/sample-resource). They allow you to organize related samples, share them with collaborators, and apply consistent permissions.
A user can own multiple projects, be a member of projects owned by others, and (with appropriate permissions) make projects public so they appear on the One Codex platform's public listings.
The below table summarizes all of the **properties** for the Project resource, with the JSON schema type of each property listed below in italics.
# Add A User To A Project
Source: https://developer.onecodex.com/api-reference/project-resource-add-user
POST /api/v1/projects/{id}/add_user
Grant a user access to a Project.
# Change Project Sharing
Source: https://developer.onecodex.com/api-reference/project-resource-change-sharing
POST /api/v1/projects/{id}/change_sharing
Change a Project's visibility (e.g., make it `public` or restrict it to organization members).
# Create A Project
Source: https://developer.onecodex.com/api-reference/project-resource-create
POST /api/v1/projects
Create a new Project owned by the authenticated user. The `project_name` must be unique within the user's organization and match the pattern `^[a-zA-Z0-9_-]{3,15}$`.
# Delete A Project
Source: https://developer.onecodex.com/api-reference/project-resource-delete
DELETE /api/v1/projects/{id}
Delete a Project. The caller must have administrator permission on the project. The project must be empty — if any samples are still associated with it, the request fails with a `400` and the message "Project has one or more samples in it. Please remove the sample(s) from the project before deleting the project." Move or detach samples first via [PATCH on the sample](/api-reference/sample-resource-patch).
# Retrieve A Project
Source: https://developer.onecodex.com/api-reference/project-resource-get
GET /api/v1/projects/{id}
GET a single Project by its ID.
# Retrieve All Projects
Source: https://developer.onecodex.com/api-reference/project-resource-instances
GET /api/v1/projects
GET all Project instances visible to the authenticated user. Returns a paginated list of Projects the user owns or is a member of.
# Retrieve Public Projects
Source: https://developer.onecodex.com/api-reference/project-resource-instances-public
GET /api/v1/projects/public
GET the paginated list of all public Projects. Includes any project whose `public` attribute is `true`, regardless of who owns it.
# List Project Members
Source: https://developer.onecodex.com/api-reference/project-resource-members
GET /api/v1/projects/{id}/members
List the users who have been granted access to a Project. Each member has a set of permissions describing what they can do within the project (e.g., `can_see_files`, `can_add_files`, `can_edit_metadata`, `can_download_files`).
# Update A Project
Source: https://developer.onecodex.com/api-reference/project-resource-patch
PATCH /api/v1/projects/{id}
Update the human-readable `name`, `description`, or `external_id` of a Project. To change who can access a project or its visibility, see [Change Project Sharing](/api-reference/project-resource-change-sharing) and the `add_user` / `remove_user` endpoints.
# Remove A User From A Project
Source: https://developer.onecodex.com/api-reference/project-resource-remove-user
POST /api/v1/projects/{id}/remove_user
Revoke a user's access to a Project. The caller must own the project (or have an organization-level role that allows project administration). The project's owner cannot be removed via this endpoint — use [Delete A Project](/api-reference/project-resource-delete) instead.
# Rate Limits
Source: https://developer.onecodex.com/api-reference/rate-limits
To ensure fair usage and maintain API performance, the One Codex API enforces a rate limit of **10 requests per second** per client.
## Limit Scope
The rate limit is shared across all API routes. For example, requests to both `https://app.onecodex.com/api/v1/samples` and `https://app.onecodex.com/api/v1/analyses` count toward the same 10 requests/second limit.
## Exceeding the Limit
If your application exceeds the allowed request rate, the API will respond with an HTTP **`429 Too Many Requests`** status code. No further requests will be processed until the rate falls back within the allowed threshold.
**EXAMPLE RESPONSE**
```http http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"msg": "Rate limited.",
"status": 429
}
```
## Handling 429 Responses
Clients should implement a retry strategy, such as exponential backoff, to gracefully handle 429 responses and avoid overwhelming the API. We recommend monitoring your request rate and implementing safeguards in your integration to stay within the defined limits.
Our [Python client library](https://github.com/onecodex/onecodex) and [command line client](https://github.com/onecodex/onecodex) automatically retry requests when they receive a 429 (rate limit) response.
# The Sample Resource
Source: https://developer.onecodex.com/api-reference/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 20GB in size. Uploading samples requires 2 direct API calls, one to start the upload and a second to actually POST the FASTA or FASTQ files. If you need to upload a compressed file *over* 20GB in size, please contact us for help at [support@onecodex.com](mailto:support@onecodex.com).
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.
*Note: Samples imported via an external service (e.g., BaseSpace) may also be marked as `importing` until One Codex's servers have successfully retrieved the file. These samples are always private to the `owner` of the sample.*
The table below shows all of the **properties** for the Sample resource.
# Confirming an Upload
Source: https://developer.onecodex.com/api-reference/sample-resource-confirm-upload
POST /api/v1/samples/confirm_upload
Confirms the upload. See [Starting an Upload](/api-reference/sample-resource-upload-file) for more details on the full upload workflow.
# Delete A Sample
Source: https://developer.onecodex.com/api-reference/sample-resource-delete
DELETE /api/v1/samples/{id}
Delete a Sample.
# Downloading Sequence Data
Source: https://developer.onecodex.com/api-reference/sample-resource-download
POST /api/v1/samples/{id}/download_uri
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](/api-reference/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).
# Retrieve A Sample
Source: https://developer.onecodex.com/api-reference/sample-resource-get
GET /api/v1/samples/{id}
GET a single sample by its ID.
# Retrieve All Samples
Source: https://developer.onecodex.com/api-reference/sample-resource-instances
GET /api/v1/samples
GET all Sample instances. Returns a paginated list of Samples.
# Retrieve Public Samples
Source: https://developer.onecodex.com/api-reference/sample-resource-instances-public
GET /api/v1/samples/public
GET all publicly-listed samples. Returns a paginated list of Samples.
# Updating Samples
Source: https://developer.onecodex.com/api-reference/sample-resource-patch
Patch /api/v1/samples/{id}
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 `PATCH`ing 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](mailto:support@onecodex.com) 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.
# Pre-Uploading Samples
Source: https://developer.onecodex.com/api-reference/sample-resource-preupload
POST /api/v1/samples/preupload
For situations where you'd like to create Samples on the One Codex Platform, but your NGS data is not yet available, we support a "pre-upload" workflow. Simply POST to the `/preupload` route to receive a unique sample ID. That sample ID may be then passed when uploading your data (see [Starting an Upload](/api-reference/samples-resource-upload-file)) to upload data for the pre-uploaded sample instead of creating a new sample.
Samples created via the `/preupload` route will have a visibility property with a value awaiting data. These samples and their metadata will be `private`, though they may be shared with other accounts if associated with a project at creation time (see [Sharing & Projects](https://docs.onecodex.com/en/articles/3764345-sharing-projects) for more details on sharing data via projects).
# Starting an Upload
Source: https://developer.onecodex.com/api-reference/sample-resource-upload-file
POST /api/v1/samples/init_upload
Start an upload by `POST`ing 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 20GB 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](https://httpie.org) or Python requests is:
```sh httpie theme={null}
# 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"
```
```python Python theme={null}
# 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'), ''))
```
# The Sequencing Batch Resource
Source: https://developer.onecodex.com/api-reference/sequencing-batch-resource
Sequencing Batches represent sets of samples that are being processed at the One Codex sequencing lab. Batches are what associate physical tubes with `Sample` objects in One Codex, and help you track samples through the sequencing process.
This section includes docs on how to list your sequencing batches, retrieve an individual batch, and register samples to a new batch.
# Retrieve A Sequencing Batch
Source: https://developer.onecodex.com/api-reference/sequencing-batch-resource-get
GET /api/v1/sequencing/batches/{id}
GET a single Sequencing Batch by its ID.
# Retrieve All Sequencing Batches
Source: https://developer.onecodex.com/api-reference/sequencing-batch-resource-instances
GET /api/v1/sequencing/batches
GET all Sequencing Batch instances. Returns a paginated list of Sequencing Batches.
# Registering a Sequencing Batch
Source: https://developer.onecodex.com/api-reference/sequencing-batch-resource-post
POST /api/v1/sequencing/batches/register
You can let One Codex know about sequencing samples that are inbound to our lab by registering them as part of a Sequencing Batch. A Batch can have one or more samples associated with it, and lets you associate the tube barcodes for the Reformatting or Sample Collection tubes you have with `Sample` objects in One Codex.
The response from this endpoint will give you a list of Samples, each with an identifier and the tube barcode it is associated with. You should store this identifier so that you can [update Sample metadata](/api-reference/metadata-resource-patch) or retrieve the Sample later on.
# Retrieve Samples in a Sequencing Batch
Source: https://developer.onecodex.com/api-reference/sequencing-batch-resource-samples
GET /api/v1/sequencing/batches/{id}/samples
GET all samples in given Sequencing Batch. Returns a paginated list of objects including the `tube_barcode` and the `sample` resource.
# The Tag Resource
Source: https://developer.onecodex.com/api-reference/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](/api-reference/sample-resource-patch)).
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](https://en.wikipedia.org/wiki/Multilocus_sequence_typing).
![]()
By convention, tags created automatically by our system have lighter colors and dark text. User-created tags have bolder colors with white text.
# Create A Tag
Source: https://developer.onecodex.com/api-reference/tag-resource-create
POST /api/v1/tags
Create a new Tag and attach it to a sample. Samples can have multiple tags, and samples can be queried by tag — see [Retrieve All Samples](/api-reference/sample-resource-instances).
# Retrieve A Tag
Source: https://developer.onecodex.com/api-reference/tag-resource-get
GET /api/v1/tags/{id}
GET a single tag by its ID.
# Retrieve All Tags
Source: https://developer.onecodex.com/api-reference/tag-resource-instances
GET /api/v1/tags
GET all tags. Returns a paginated list of tags.
# Uploading Documents Overview
Source: https://developer.onecodex.com/api-reference/uploading-documents
Documents 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. In every case, we replace spaces in filenames with underscores. To upload with the CLI, simply:
```shell shell theme={null}
# 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
onecodex documents upload $LIST_OR_GLOB_OF_YOUR_DOCUMENTS
```
Uploading via the REST API consists of 3 steps:
* (1) Initiating an upload by POSTing to [`/documents/init_upload`](/api-reference/document-resource-upload-file)
* (2) Uploading the document to the provided `upload_url` and with any `additional_fields` provided. See the [Starting an Upload](/api-reference/document-resource-upload-file) documentation for more details.
* (3) Confirming the upload by POSTing to [`/documents/confirm_upload`](/api-reference/document-resource-confirm-upload)
## Documents over 20GB
The above upload mechanisms currently only allow document uploads up to 20GB (optionally compressed with `gzip`). If you need to upload a compressed file *over* 20GB, please contact us at [support@onecodex.com](mailto:support@onecodex.com) and we can provide an alternative upload or file import mechanism for your situation.
# Uploads Overview
Source: https://developer.onecodex.com/api-reference/uploading-samples
FASTA and FASTQ files 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). In every case, we replace spaces in filenames with underscores. To upload with the CLI, simply:
```shell shell theme={null}
# 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:
* (1) Initiating an upload by POSTing to [`/samples/init_upload`](/api-reference/sample-resource-upload-file)
* (2) Uploading the sample to the provided `upload_url` and with any `additional_fields` provided. See the [Starting an Upload](/api-reference/sample-resource-upload-file) documentation for more details.
* (3) Confirming the upload by POSTing to [`/samples/confirm_upload`](/api-reference/sample-resource-preupload)
## Samples over 20GB
The REST upload above only allows sample uploads up to 20GB (optionally compressed with `gzip`). If you need to upload a compressed file *over* 20GB, please use the `onecodex` CLI.
# The User Resource
Source: https://developer.onecodex.com/api-reference/user-resource
A User represents a single account-holder on the One Codex platform.
The below table summarizes all of the **properties** for the User resource, with the JSON schema type of each property listed below in italics.
# Retrieve A User
Source: https://developer.onecodex.com/api-reference/user-resource-get
GET /api/v1/users/{id}
GET a single User by its ID. Visibility follows the same organization- and project-level rules as the [list endpoint](/api-reference/user-resource-instances).
# Retrieve All Users
Source: https://developer.onecodex.com/api-reference/user-resource-instances
GET /api/v1/users
GET all Users visible to the authenticated user.
# Using Webhooks
Source: https://developer.onecodex.com/api-reference/using-webhooks
Currently, webhooks are only available for paid users and partners. Please [contact us](mailto:support@onecodex.com) to get webhooks set up for your account.
## Overview
In addition the above resources, we also allow users to set up webhooks and subscribe to Events that occur as your Samples and Analyses are processed by the platform. Events are a record of webhook payloads that have been delivered to relevant subscriptions and ***only exist*** if webhooks are configured (i.e., an account without webhooks turned on will have no events). By default, up to 30 days worth of events are available via the v1 API.
## Subscribing to webhooks
Currently, it is possible to subscribe to individual event types or subscribe to all events (`*`). Webhooks POST to a specified `http` or `https` endpoint without authentication and are individually signed and timestamped so that you can verify that the webhooks were sent by One Codex and not a third party (see [Checking Signatures](/api-reference/checking-webhook-signatures)). Please [contact us](mailto:support@onecodex.com) in order to get started with webhooks for your account.
## Event types
Currently the following event types exist:
* `sample.uploaded`: When a sample is successfully uploaded *or* imported into the One Platform. This event means we have successfully received your data and started to process it.
* `analysis.succeeded`: When an analysis finishes successfully. Successful analyses have a `success: true` property and their results may be retrieved via the API (see [Retrieve Analysis Results](/api-reference/analysis-resource-results)).
* `analysis.failed`: When an analysis finishes but is unsuccessful. Failed analyses will have `/results` that result in a `404` error and a `success: false` property. Note that an `analysis.failed` event *may* fire multiple times for the same analysis if it is retried by One Codex's processing (it may also `succeed` in the future if the failure was due, e.g., to hardware or other unexpected processing issues).
*Note that the default "wildcard" subscriptions (`*`) may include additional event types in the future. When requesting that webhook setup for your account, please specify if you would like the subscription(s) to listen to all events or only select events.*
## The Event resource
The event resource contains the following fields:
| Property | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\$uri** *string* | The event ID encoded as an addressable URI |
| **payload** *object* | The webhook payload (as documented below). Note that webhooks will be delivered for a specific API version and that version is noted in the payload via the `api_version` field. **Only** `v1` API version payloads, however, will appear in the `/v1/events` API. |
| **status** *string* | An enum with one of the following 4 values:`success`: Successful POSTs were made to all subscriptions (all returned 200 OK). `failed`: At least one subscription returned a non-200 HTTP status code or connection error for every POST attempt made, and all retries were exhausted.`retryable`: At least one subscription POST failed, but there are still retries remaining before the Event will be marked as `failed`. `pending`: There is at least one subscription to this Event, and no attempts have yet been made to send out POSTs. |
## The Webhook payload format
The webhook payload delivered by our system consists of 5 fields:
| | |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **api\_version** *string* | The API version used in generating the representation of the relevant `object` field. |
| **event\_type** *string* | A string with the event type. Note webhooks may be configured to listen to all or only specific event types. |
| **object** *object* | A representation of the core object for which the `event_type` was triggered for the specified `api_version`. |
| **object\_type** *string* | A string representation of the object type. Currently `sample` and `analysis` are the only supported values, indicating that the `object` is a [Sample Resource](/api-reference/sample-resource) or [Analysis Resource](/api-reference/analysis-resource), respectively. |
| **triggered\_at** *date-time* | Timestamp for when the event was triggered, encoded as a [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) timestamp. **Note**: The `triggered_at` field is *not* when the webhook was sent (which may be later due to retries or processing delays). The timestamp for the payload POST is included in the `X-OneCodex-Signature` HTTP header (see [Checking Signatures](/api-reference/checking-webhook-signatures) below). |
In production settings, we strongly recommend checking the signatures of any received webhooks to ensure that they originate from One Codex and not a malicious third party. See the [following section](/api-reference/checking-webhook-signatures) for details.
# The Webhook Resource
Source: https://developer.onecodex.com/api-reference/webhook-resource
Webhooks let your application receive HTTP callbacks when events happen on the One Codex platform — for example, when a sample finishes uploading or an analysis completes. See [Using Webhooks](/api-reference/using-webhooks) for a walkthrough and [Checking Webhook Signatures](/api-reference/checking-webhook-signatures) for verification details.
The below table summarizes all of the **properties** for the Webhook resource, with the JSON schema type of each property listed below in italics.
# Retrieve A Webhook
Source: https://developer.onecodex.com/api-reference/webhook-resource-get
GET /api/v1/webhooks/{id}
GET a single Webhook by its ID.
# Retrieve All Webhooks
Source: https://developer.onecodex.com/api-reference/webhook-resource-instances
GET /api/v1/webhooks
GET all Webhooks registered by the authenticated user.
# The Workflow Resource
Source: https://developer.onecodex.com/api-reference/workflow-resource
A Workflow run is an analysis produced by a user-defined [Workflow](/workflows/workflows-introduction) — a versioned, containerized pipeline executed on the One Codex platform. Workflow runs are produced by jobs whose `analysis_type` is `workflow`. See the Workflows documentation tab for authoring and running workflows.
The below table summarizes all of the **properties** for the Workflow resource, with the JSON schema type of each property listed below in italics.
# Retrieve A Workflow Run
Source: https://developer.onecodex.com/api-reference/workflow-resource-get
GET /api/v1/workflows/{id}
GET a single Workflow run by its ID.
# Retrieve All Workflow Runs
Source: https://developer.onecodex.com/api-reference/workflow-resource-instances
GET /api/v1/workflows
GET all Workflow runs visible to the authenticated user. Returns a paginated list.
# Workflow Results
Source: https://developer.onecodex.com/api-reference/workflow-resource-results
GET /api/v1/workflows/{id}/results
GET the structured results for a single Workflow run — the output payload defined by the workflow's `results.json` file. See [Adding a `results.json` file](/workflows/adding-a-resultsjson-file).
# Accessing Parameters (arguments)
Source: https://developer.onecodex.com/workflows/accessing-parameters
Any parameters that are defined for your workflow either as part of the workflow definition or by the user at the time of analysis kickoff are injected into the execution environment as environment variables.
If your workflow is configured as a Nextflow workflow, we also inject a parameters file containing the complete set of arguments for that instance of the workflow. You can pass these to Nextflow via the `--params-file` flag in the workflow script.
To access the argument in your script, we will prepend `ARGS_` to the name, and we will capitalize the name. For instance, if you named your argument `your_argument_1`, you can access this in the script as `$ARGS_YOUR_ARGUMENT_1`. Any such parameters will be visible on the workflow creation page to the right of your script, and you will see a clipboard icon beside the argument name, allowing you to copy the name for use throughout your script.
## Accessing Arguments at Workflow Launch
Any parameters that are marked as required must be passed when launching the workflow. If required arguments have default values, these default values will automatically be populated in the web app, but they are not assumed when launching via the API, and must be provided, even if default values are being used.
To override the default parameters for a workflow run, or to set values for parameters that do not have defaults, you can:
1. Pass the values in the confirmation screen when launching via the web app
2. If launching the workflow via API, you can provide the arguments directly in the command, or store them in a .json file. For instance, if you saved the below as `my_workflow_arguments.json`:
```json json theme={null}
{
"sample":"the UUID of the sample you want to run the analysis on",
"job_args": {
"your_argument_1": "arg_1_value",
"your_argument_2": "arg_2_value",
}
}
```
* You can run the workflow, with the above arguments on the sample provided in the JSON, with the below command
```sh curl theme={null}
curl -u $ONE_CODEX_API_KEY: -H "Content-Type: application/json" -d @my_workflow_arguments.json -X POST https://app.onecodex.com/api/v1/jobs/[workflow_UUID]/run
```
* where `$ONE_CODEX_API_KEY` is your API key,
* `workflow_UUID` is the unique identifier for the workflow that you want to run on the sample
3. Alternatively, you can pass the arguments directly to the cURL command, such as:
```sh curl theme={null}
curl -u $ONE_CODEX_API_KEY: -H "Content-Type: application/json" -d {"sample":"[sample_UUID]", "job_args":{"your_argument_1": "arg_1_value","your_argument_2": "arg_2_value",}} -X POST https://app.onecodex.com/api/v1/jobs/[workflow_UUID]/run
```
***
**What’s next?** Need to make some files available to multiple workflows? Use our Assets feature!
# Adding a results.json file
Source: https://developer.onecodex.com/workflows/adding-a-resultsjson-file
A key feature of One Codex is the ability to retrieve a structured, machine-readable version of the results of your workflow over our REST API. All of our One Codex analyses provide this JSON result representation by default, and we've made it easy for you to include the same functionality in your workflows.
All you need to do is output a file named `results.json` with a valid, JSON-encoded representation of your analysis results at the top level of the working directory. When your workflow completes, we will automatically search for this file, and if found we'll parse the contents and make them accessible to you via the `/api/v1/analyses//results` API route.
If you have a `results.json` file in the working directory that is empty or does not contain valid JSON, we will consider the analysis to have failed.
At the moment, your `results.json` file can contain *any* JSON object you'd like. We don't validate the contents of the JSON, just that it is valid JSON. That means you can feel free to follow whatever schema you'd like.
In the future, we will offer particular schema definitions that will let us e.g. provide you with more enhanced, dynamic results visualizations for your workflows. Once we release those, we'll give you the option to opt-in to having your `results.json`file validated against those schemas. But for now, let your imagination run wild!
***
**What’s next?** Learn how outputs are made available.
# Connecting your GitHub Repository
Source: https://developer.onecodex.com/workflows/connecting-your-github-repository
As an organization owner or admin, you can integrate One Codex with GitHub from your [settings page](https://app.onecodex.com/settings) (click your name at the top-right of the One Codex site, and choose Settings). Towards the bottom of your settings page, you'll see a section for GitHub Integration.
There are two ways to connect your One Codex account to GitHub; either via our GitHub App, or via a GitHub Personal Access Token.
![]()
## One Codex GitHub App
One Codex has developed a GitHub app, which an organization owner or admin can install on behalf of all organization members. If installed, the GitHub app takes precedence over individual Personal Access Tokens. Clicking "Install One Codex GitHub App" takes you to GitHub. Once logged in, you can choose which GitHub organization(s) you wish to install the app for. Once you've selected you organization, you will be able to choose whether to provide access to all repositories, or only selected repositories.
![]()
You will need to be a GitHub Organization Owner in order to be able to provide access to the repositories.
## GitHub Personal Access Token
If you don't want to connect GitHub for all members in your One Codex organization, you can instead choose to connect via your own Personal Access Token. Note that if the GitHub integration app is enabled, you will not be able to provide a Personal Access Token, as the app integration takes precedence.
To generate a Personal Access Token, you will need to follow [these GitHub steps](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token). Use a **fine-grained** token, and fill in GitHub's token form as follows:
| GitHub setting | What to choose | Why |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Resource owner** | The user or organization that owns the repositories you want to run on One Codex. | The token can only ever reach repositories under this owner. |
| **Expiration** | Any date you like. We suggest **1 year**. | Shorter expirations are more secure but mean more frequent rotation. See the warning below. |
| **Repository access** | **Only select repositories**, then pick just the repositories you want to run as One Codex Workflows. | Least privilege. Avoid "All repositories" so the token can't read anything else you own. |
| **Permissions → Repository permissions → Contents** | **Read-only** | Required. One Codex uses it to read your repository tags and `nextflow_schema.json`, and to clone the repository into the Workflow at run time. Without it you may still be able to save the Workflow, but its runs will fail to clone the repository. |
`Contents: Read-only` is the only permission One Codex needs. GitHub automatically adds `Metadata: Read-only` alongside it, which is expected. Leave every other permission set to "No access", and don't grant any write permissions.
A Workflow that uses a private repository stops being runnable once its Personal Access Token expires or is revoked. Existing results are unaffected, but new runs will fail until you add a fresh token in your [One Codex settings](https://app.onecodex.com/settings). Set a calendar reminder ahead of the expiration date, or use the GitHub App integration instead, which does not expire.
Once the token is generated, copy it and paste it into the GitHub Personal Access Token field on your [One Codex settings page](https://app.onecodex.com/settings). Tokens are stored encrypted, and GitHub will only show you the token value once.
## Using your repository in a workflow
When a workflow has a Git repository configured, the repository is cloned into the workflow's working directory before your script runs. The name of that directory is available as the `$REPOSITORY_DIR` environment variable, e.g. `my-pipeline` for `https://github.com/my-org/my-pipeline`:
```bash theme={null}
ls -lah "$REPOSITORY_DIR"
# Nextflow workflows
nextflow run "${REPOSITORY_DIR}/main.nf" --outdir "output-$OCX_ANALYSIS_UUID"
```
You do not need to clean up the cloned repository. It is excluded from the files captured as [workflow outputs](/workflows/output-directories-and-files), so it will not show up in your results.
## Disconnecting From GitHub
If you have connected via the GitHub app, returning to your settings page, you will see a button to remove the GitHub App integration. Note that this does not uninstall the app from GitHub. You can uninstall from GitHub by visiting your GitHub installations page.
![]()
If you have provided a GitHub Personal Access Token, you will see an option to either Update or Remove your Personal Access Token from your One Codex settings page. You can also delete your Personal Access Token within GitHub by following [these steps](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#deleting-a-personal-access-token).
![]()
# Creating an Asset
Source: https://developer.onecodex.com/workflows/creating-an-asset
Assets can be created through the One Codex web application on the [Assets page](https://app.onecodex.com/workflows/assets). There you will see two tabs: one to view assets that have already been uploaded, and another to upload new assets.
Alternatively, you can upload assets using the One Codex CLI or our API. Note that only organization editors, admins, or owners may create assets.
```shell shell theme={null}
# You can use the One Codex CLI to upload your assets.
# You will need to log in first.
onecodex --api-key $ONE_CODEX_API_KEY login
# Then begin your upload
onecodex assets upload $filename
```
```sh curl theme={null}
# Start the upload
curl -u $ONE_CODEX_API_KEY: \
-X POST \
https://app.onecodex.com/api/v1/assets/init_multipart_upload
# This should return a response with the following JSON body:
#{
# "callback_url": "/api/v1/assets/confirm_multipart_upload",
# "file_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
# "s3_bucket": "onecodex-multipart-uploads-encrypted",
# "upload_aws_access_key_id": "XXXXXXXXXXXXXXXXXXXX",
# "upload_aws_secret_access_key": "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
#}
# You can then upload your file to our AWS bucket
AWS_ACCESS_KEY_ID=$upload_aws_access_key_id \
AWS_SECRET_ACCESS_KEY=$upload_aws_secret_access_key \
aws s3 cp $filename \
"s3://onecodex-multipart-uploads-encrypted/$file_id" --sse
# Once the upload has completed, you will need to confirm it
curl -u $ONE_CODEX_API_KEY: \
-X POST -H "Content-Type: application/json" \
"https://app.onecodex.com/api/v1/assets/confirm_multipart_upload" \
-d @- << EOF
{
"s3_path": "s3://onecodex-multipart-uploads-encrypted/$file_id",
"filename": "$filename",
"name": ""
}
EOF
```
# Definining parameters (arguments)
Source: https://developer.onecodex.com/workflows/defining-parameters
## For Shell script/Docker workflows
When creating your workflow, you will see a section for Arguments to the right of your script. While in a draft state, you can add/remove arguments from this section. For each argument, we will provide fields for the following details:
* **Name:** Provide a name for your argument. When launching the analysis for a sample via the API, you can pass this name and its value. To access the argument in your script, we will prepend `ARGS_` to the name, and we will capitalize the name. For instance, if you named your argument `your_argument_1`, you can access this in the script as `$ARGS_YOUR_ARGUMENT_1`.
* **Type:** Choose from a dropdown menu for the value type, such as `boolean`, `number`, `integer`, `regex`, `string`.
* **Required:** Check the box to determine if this argument is a required argument. If you check the box, you must provide a value at the time of launch.
* **Description:** An optional field to provide details on what this argument is for.
## For Nextflow workflows
Nextflow workflows use the `nextflow_schema.json` file, which must be stored in the root directory of your GitHub repository, to define the parameters that will be used by the workflow. These arguments will be visible on the workflow edit/details page, where you can additionally set whether the argument is required or not.
To access the argument in your script, we will prepend `ARGS_` to the name, and we will capitalize the name. For instance, if you named your argument `your_argument_1`, you can access this in the script as `$ARGS_YOUR_ARGUMENT_1`.
For Nextflow workflows, your argument values will be written to a file named `input_params.json`, which you will pass to your `nextflow run` command, such as:
```
nextflow run "${REPOSITORY_DIR}/main.nf" \
-params-file input_params.json \
--outdir output-$OCX_ANALYSIS_UUID
```
## Setting Argument Values at Launch
Any parameters that are marked as required must be passed when launching the workflow. If required arguments have default values, these default values will automatically be populated in the web app, but they are not assumed when launching via the API, and must be provided, even if default values are being used.
To override the default parameters for a workflow run, or to set values for parameters that do not have defaults, you can:
1. Pass the values in the confirmation screen when launching via the web app
2. If launching the workflow via API, you can provide the arguments directly in the command, or store them in a .json file. For instance, if you saved the below as `my_workflow_arguments.json`:
```json json theme={null}
{
"sample":"the UUID of the sample you want to run the analysis on",
"job_args": {
"your_argument_1": "arg_1_value",
"your_argument_2": "arg_2_value",
}
}
```
* then you can run the workflow, with the above arguments on the sample provided in the JSON, with the below command
```sh curl theme={null}
curl -u $ONE_CODEX_API_KEY: -H "Content-Type: application/json" -d @my_workflow_arguments.json -X POST https://app.onecodex.com/api/v1/jobs/[workflow_UUID]/run
```
* where `$ONE_CODEX_API_KEY` is your API key,
* `workflow_UUID` is the unique identifier for the workflow that you want to run on the sample
3. Alternatively, you can pass the arguments directly to the cURL command, such as:
```
curl -u $ONE_CODEX_API_KEY: -H "Content-Type: application/json" -d {"sample":"[sample_UUID]", "job_args":{"your_argument_1": "arg_1_value","your_argument_2": "arg_2_value",}} -X POST https://app.onecodex.com/api/v1/jobs/[workflow_UUID]/run
```
***
**What’s next?** Now that you've defined your parameters, learn how to set them.
# Deleting an Asset
Source: https://developer.onecodex.com/workflows/deleting-an-asset
Because assets are shared with all members of your organization, only organization editors, admins, or owners are permitted to delete them. An asset that is already used by an analysis job cannot be deleted. Deleting an asset also removes its underlying file from One Codex storage.
To delete an asset, you will need its UUID, which you can obtain by [listing your assets](/workflows/listing-your-assets) (the UUID is the final segment of the asset's `$uri`). Then use it in the request below:
```sh curl theme={null}
curl -u $ONE_CODEX_API_KEY: \
-X DELETE \
"https://app.onecodex.com/api/v1/assets/"
```
***
**What’s next?** Learn about accessing your results!
# Developing on One Codex
Source: https://developer.onecodex.com/workflows/developing-on-one-codex
These are a handful of good-to-know points about adapting your workflows to run on One Codex.
## Where will my FASTQ file for my input sample be located?
The FASTQ file corresponding to the `Sample` the workflow was run on will be injected into the working directory and gzip'ed. You can get the filename for the sample via the `OCX_SAMPLE_FILENAME` environment variable.
Whenever a file is uploaded to One Codex, the platform decompresses, validates, (optionally) interleaves, and recompresses the file using GZIP compression. That means you can always expect to use a valid GZIP'ed FASTA or FASTQ file as input in your workflow, with paired end reads interleaved one after another.
If the uploaded file was compressed using a different compression scheme like BGZIP, that will not be retained and the file will be re-compressed with regular GZIP. If your workflow relies on a BGZIP-compressed input, you'll need to extract and recompress the file at the beginning of the workflow.
## Containers are run as a non-root user
All workflows on One Codex run in one or more Docker containers. These containers are always run as a non-root user as part of our security model. That means certain tools or features of the operating system might not be available to your workflow, such as `ulimit`. If this prevents you from being able to run your workflow on One Codex, [reach out to us](mailto:support@onecodex.com) and we'll help you out!
***
**What's next?** Learn about setting up your Environment Variables
# Docker Images
Source: https://developer.onecodex.com/workflows/docker-images
When creating your "shell" (non-Nextflow) workflow, we will provide a default Docker image URI, which uses Ubuntu. If you wish to use an alternative Docker image, you may provide the URI for the image.
Docker image URIs must be publicly accessible. If you require a private image, reach out to our team.
For Nextflow workflows, instead of an image, you can choose from our pre-installed Nextflow versions.
# Environment Variables
Source: https://developer.onecodex.com/workflows/environment-variables
Environment variables about the analysis and sample are injected into every workflow for your convenience.
The follow environment variables are available to your workflow:
| Environment Variable | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OCX_SAMPLE_FILENAME` | The normalized filename of the FASTA/Q file that was uploaded to One Codex. This will correspond to the name of the file that is injected into the working directory for your workflow. |
| `OCX_SAMPLE_NAME` | The name of the `Sample` in One Codex. This might be different from the filename if the user has edited the `Sample` metadata. |
| `OCX_SAMPLE_UUID` | The UUID of the `Sample` in One Codex. This is a globally unique identifier for the `Sample` that was used as input for the workflow. |
| `OCX_ANALYSIS_UUID` | The UUID of the current `Analysis` in One Codex. This is a globally unique identifier for the current workflow run on a particular sample with the specific set of input parameters. This can be used to globally identify a particular instance of an `Analysis` in One Codex. |
| `OCX_CPU_REQUEST` | The number of CPUs requested for your workflow. Pass this to multi-threaded tools so they use all the CPUs available to the run. |
| `OCX_INSTRUMENT_VENDOR` | The name of the sample's instrument vendor (e.g., "Illumina", "Oxford Nanopore"). |
| `OCX_IS_LONG_READ` | `"true"` if the sample is detected to be from a long read sequencer (e.g., PacBio or ONT); `"false"` otherwise. |
| `OCX_DEPENDENCY_UUIDS` | Space-separated list of `Analysis` UUIDs that the current analysis depends on. |
| `REPOSITORY_DIR` | The name of the directory in the working directory that your workflow's Git repository was cloned into (e.g. `my-pipeline` for `https://github.com/my-org/my-pipeline`). Only set if the workflow has a Git repository configured. See [Connecting your GitHub Repository](/workflows/connecting-your-github-repository). |
## Workflow Parameters as Environment Variables
Any parameters that are defined for your workflow either as part of the workflow definition or by the user at the time of analysis kickoff are injected into the execution environment as environment variables.
***
**What’s next?** Learn the specifics of Nextflow on One Codex.
# Introduction to Assets
Source: https://developer.onecodex.com/workflows/introduction-to-assets
Assets are a straightforward way to include reference data such as genome databases or primer files that are required by your workflow. You can upload an asset via the One Codex web application, our API, or our command-line interface (CLI).
Assets are shared with all members of your organization, so a single upload can be re-used across users and workflows. Once you've uploaded an asset, you can select it when defining your workflow, and it will be automatically injected into the working directory each time the workflow runs.
The contents of an asset are immutable once uploaded, which means the reproducibility of your pipeline is ensured and you don't need to worry about the availability of external resources when you run your workflow on One Codex.
# Listing your Assets
Source: https://developer.onecodex.com/workflows/listing-your-assets
You can list the assets available to your organization using the following:
```sh curl theme={null}
curl -u $ONE_CODEX_API_KEY: \
-X GET \
"https://app.onecodex.com/api/v1/assets"
```
This will return a list of JSON items like the example below.
```json json theme={null}
[
{
"$uri": "/api/v1/assets/xxxxxxxxxxxxxxxx",
"created_at": "2023-11-15T18:33:18.884095+00:00",
"filename": "my_filename.json",
"name": "my_filename.json",
"size": 5243096,
"status": "available",
"uploader": {
"$ref": "/api/v1/users/YYYYYYYYYYYYYYYY"
}
}
]
```
# Nextflow on One Codex
Source: https://developer.onecodex.com/workflows/nextflow-on-one-codex
This page contains helpful information about how to run Nextflow workflows on One Codex.
## Supported Nextflow versions
We currently support the following Nextflow versions:
* 26.04.6
* 25.10.0
* 25.04.3
* 24.10.2
* 24.04.2
* 23.10.0
* 22.10.6
**Note:** Nextflow 22.04.5 has been deprecated. Existing workflows pinned to this version will continue to run, but new workflows cannot be created with it.
If your workflow requires a specific Nextflow version that is not listed here, [reach out to our team](mailto:support@onecodex.com) and let us know which version you need. We will try to add support for versions as needed.
## Debugging failed Nextflow workflows
If your workflow fails for a sample, we will show that the workflow is complete (`"complete": true`) but not successful (`"success": false`) in the json details for the workflow (accessible via `https://app.onecodex.com/api/v1/analyses/[workflow_run_UUID]`, using the unique identifier for this attempt of your workflow run).
For failed workflows, we retain the logs & output files temporarily (7 days after creation), so that you can explore the point of failure in your pipeline. You can access these files by appending `/files`to the above URL (i.e.`https://app.onecodex.com/api/v1/analyses/[workflow_run_UUID]/files`). The resulting json will list the available files as keys, and their temporary storage location (pre-signed URL) as values, so that you can download the required files.
# Output directories and files
Source: https://developer.onecodex.com/workflows/output-directories-and-files
Once a workflow has completed, any temporary files will automatically be purged. If there are any files that you wish to keep, you will need to place them into a new directory inside the main working directory. This new directory needs to be named `output`, or at a minimum must be prefixed with `output`. We recommend using `output-$OCX_ANALYSIS_UUID`, to allow for easier distinction between outputs from various workflow runs. For Nextflow workflows, this would mean using `--outdir output-$OCX_ANALYSIS_UUID` in your `nextflow run` command.
Files that are stored in the `output` directory will be displayed as outputs on the results page of a workflow. The `output` directory and any sub-directories can be expanded to view the full tree of results files. Results files can be individually downloaded. There is also an option to download the entire output directory, via the "Download Results" button at the top-right of the results page. We will automatically tar and gzip the `output` directory for simplified download.
If your workflow has a Git repository configured, the cloned repository directory (`$REPOSITORY_DIR`) is excluded from the captured outputs, so you don't need to clean it up in your script.
If your workflow generates >1000 files, we will tarball and gzip the `output `directory. You will not be able to list or download the individual files within the `output` folder on the results page. You will instead need to download the entire directory.
***
**What’s next?** Ready to start developing? [Run your workflows!](https://app.onecodex.com/workflows)
# Using an Asset in your Workflow
Source: https://developer.onecodex.com/workflows/using-an-asset-in-your-workflow
On the workflow edit page, you will see an Assets section to the right of the code window. Click "Add Asset" to add a new asset slot, which includes a dropdown menu for selecting one of your organization's assets to make available for this workflow.
Each selected asset is injected into the workflow environment under the `/share` directory. The exact path the asset will be written to is displayed at the top of the asset's box, alongside a clipboard icon you can use to copy the path into your script. The path is typically `/share/asset_/`. If the asset's filename ends in `.tar.gz`, its archive contents are extracted into `/share/asset_/` instead.
## Using Assets in Nextflow workflows
Assets are available in both shell/Docker and Nextflow workflows. When using an asset in a Nextflow workflow, only the primary Nextflow process (i.e., the script running your `nextflow run` command) has access to the `/share` directory and your asset. If any child processes need the asset, you will need to pass the asset's filepath to your Nextflow script as an argument. This allows Nextflow to distribute your asset to any child processes spawned by the main script. For example:
```
nextflow run "${REPOSITORY_DIR}/main.nf" \
-params-file input_params.json \
--my_asset_arg /share/asset_/ \
--outdir output-$OCX_ANALYSIS_UUID
```
# Workflows Introduction
Source: https://developer.onecodex.com/workflows/workflows-introduction
The Workflows feature allows One Codex users to create and run their own pipelines, right in the One Codex environment. Whether you are working with Nextflow or other scripts, you can develop your pipelines and then run them on your samples on One Codex.
The Workflows feature includes parameterization - allowing you to set parameters at the time of launching your pipeline. This means you can run your pipeline on the same sample with different variables. Learn more about parameters [here](/workflows/defining-parameters).
You may need other files to be available for various workflows. The [Assets](/workflows/introduction-to-assets) feature allows you to upload files to One Codex, and call on them in your workflows, so that they are automatically injected into the working environment on each run of a workflow.
Learn more about the various features and details of Workflows through this guide!
***
**What’s next?** Start developing your workflows!