Skip to main content
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. 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.
​
$uri
string
required
read-only
Pattern: ^/api/v1/samples/[a-f0-9]{16}$
Example:

"/api/v1/samples/0d77065796f8d173"

​
created_at
string<date-time>
required

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

​
metadata
metadata · object
required

A metadata object.

​
owner
users · object
required

The owner of the sample.

​
primary_classification
classifications · object | null
required

A reference to a Classification for the sample. This will typically be the One Codex Database or Targeted Loci Database results as appropriate. Note that samples will not have a primary_classification while they are still importing or being uploaded.

​
status
enum<string>
required

Enum for user-facing data status.

This is a subset of DataStatus for the status attribute in the APIs.

Available options:
awaiting_data,
importing,
validating,
failed_validation,
available,
deleted
​
visibility
enum<string>
required

Enum for the v1 API visibility attribute.

Note: this is legacy and only exists for backwards-compatibility in the public v1 API.

Available options:
public,
shared,
private,
importing,
awaiting data
​
error_msg
string | null

An error message if the sample failed to upload, import, or validate.

​
filename
string | null

The sample filename.

​
project
projects · object

The project the sample belongs to (optional).

​
size
integer | null

The size of the uploaded file in bytes.

​
tags
tags · object[]

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

​
updated_at
string<date-time> | null

Timestamp for when the object was last updated on the One Codex platform, encoded as a RFC 3339 timestamp.