Starting an Upload

POST

api

samples

init_upload

{
  "additional_fields": "<string>",
  "fallback_options": "<string>",
  "paired_end_additional_fields": "<string>",
  "paired_end_upload_url": "<string>",
  "sample_id": "<string>",
  "upload_url": "<string>"
}

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

Performing the acutal 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 or Python requests is:

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

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

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

# Returns a 201 response

# Confirm the upload (see below)
http --auth $ONE_CODEX_API_KEY: POST \
    https://app.onecodex.com/api/v1/samples/confirm_upload \
    sample_id="28459508592a481c"

Body

application/json

filename

string

required

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

external_sample_id

string | null

An optional external sample ID (see the Metadata resource) to match against pre-uploaded samples. Returns a 400 if no matching sample is found.

interleaved

boolean | null

Whether the file is interleaved (true) or not (false).

metadata

object

A metadata object.

metadata.custom

object

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

metadata.date_collected

string | null

Timestamp for when the sample was collected.

metadata.date_sequenced

string | null

Timestamp for when the sample was sequenced.

metadata.description

string | null

metadata.external_sample_id

string | null

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

Maximum length: 60

metadata.library_type

enum<string> | null

An enum with the sample library type.

Available options:

WGS,

Targeted/16S,

Other

metadata.location_lat

number | null

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

Required range: -90 <= x <= 90

metadata.location_lon

number | null

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

Required range: -180 <= x <= 180

metadata.location_string

string | null

Maximum length: 255

metadata.name

string | null

Maximum length: 255

metadata.platform

enum<string> | null

A enum with the name of the sequencing platform.

Available options:

454 sequencing,

454 GS FLX,

454 GS FLX Titanium,

Illumina,

Illumina Genome Analyzer II,

Illumina HiSeq,

Illumina HiSeq 1500,

Illumina HiSeq 2000,

Illumina HiSeq 2500,

Illumina HiSeq 3000,

Illumina HiSeq 4000,

Illumina HiSeq X,

Illumina iSeq 100,

Illumina MiniSeq,

Illumina MiSeq,

Illumina NextSeq,

Illumina NextSeq 500,

Illumina NextSeq 550,

Illumina NovaSeq,

Illumina NovaSeq 5000,

Illumina NovaSeq 6000,

BGISEQ,

BGISEQ 50,

Element,

Element AVITI,

Ion,

Ion S5,

Ion S5 XL,

Ion PGM,

Ion Proton,

Ion Torrent,

Oxford Nanopore,

Oxford Nanopore GridION X5,

Oxford Nanopore MinION,

Oxford Nanopore PromethION,

PacBio,

PacBio RS II,

PacBio Sequel,

PacBio Sequel II System,

PacBio Revio,

PacBio Onso,

SOLiD,

Solexa Genome Analyzer,

Sanger,

Other

metadata.sample_type

enum<string> | null

An enum with the sample type.

Available options:

Isolate,

Metagenomic,

Other

metadata.starred

boolean

default:false

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

paired_end_filename

string | null

Optional filename for paired end uploads.

project

object

An optional project into which to upload the sample.

sample_id

string | null

An optional sample ID to match against pre-uploaded samples. Returns a 400 if no matching sample is found.

size

integer | null

The size of the file in bytes.

Required range: x >= 1

Response

200 - application/json

Successful operation

additional_fields

string | null

Additional fields to include in the object storage POST request.

fallback_options

string | null

Fallback options for the upload. Please contact support for help as needed.

paired_end_additional_fields

string | null

Additional fields to include in the object storage POST request for the paired end file (optional).

paired_end_upload_url

string | null

Object storage location to POST the paired end file to (optional).

sample_id

string

The sample ID. Use to confirm the upload.

upload_url

string

Object storage location to POST the file to.

Uploads Overview Confirming an Upload

{
  "additional_fields": "<string>",
  "fallback_options": "<string>",
  "paired_end_additional_fields": "<string>",
  "paired_end_upload_url": "<string>",
  "sample_id": "<string>",
  "upload_url": "<string>"
}

API Basics

Samples

Metadata & Tags

Analyses

Jobs

Documents

Webhooks & Events

Sequencing

Performing the acutal upload – “standard” upload type

Body

Response

API Basics

Samples

Metadata & Tags

Analyses

Jobs

Documents

Webhooks & Events

Sequencing

​Performing the acutal upload – “standard” upload type

Body

Response

Performing the acutal upload – “standard” upload type