Starting an Upload

POST samples instances_init_upload

curl --request POST \
  --url https://app.onecodex.com/api/v1/samples/init_upload \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "filename": "<string>",
  "external_sample_id": "<string>",
  "interleaved": true,
  "metadata": {
    "custom": {},
    "date_collected": "2023-11-07T05:31:56Z",
    "date_sequenced": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "external_sample_id": "LIMS-2024-00123",
    "location_lat": 0,
    "location_lon": 0,
    "location_string": "<string>",
    "name": "<string>",
    "starred": false
  },
  "paired_end_filename": "<string>",
  "project": {
    "__DOLLAR_REF__": "/api/v1/projects/a1b2c3d4e5f67890"
  },
  "sample_id": "<string>",
  "size": 1,
  "tags": [],
  "upload_type": "standard"
}
'

import requests

url = "https://app.onecodex.com/api/v1/samples/init_upload"

payload = {
    "filename": "<string>",
    "external_sample_id": "<string>",
    "interleaved": True,
    "metadata": {
        "custom": {},
        "date_collected": "2023-11-07T05:31:56Z",
        "date_sequenced": "2023-11-07T05:31:56Z",
        "description": "<string>",
        "external_sample_id": "LIMS-2024-00123",
        "location_lat": 0,
        "location_lon": 0,
        "location_string": "<string>",
        "name": "<string>",
        "starred": False
    },
    "paired_end_filename": "<string>",
    "project": { "__DOLLAR_REF__": "/api/v1/projects/a1b2c3d4e5f67890" },
    "sample_id": "<string>",
    "size": 1,
    "tags": [],
    "upload_type": "standard"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filename: '<string>',
    external_sample_id: '<string>',
    interleaved: true,
    metadata: {
      custom: {},
      date_collected: '2023-11-07T05:31:56Z',
      date_sequenced: '2023-11-07T05:31:56Z',
      description: '<string>',
      external_sample_id: 'LIMS-2024-00123',
      location_lat: 0,
      location_lon: 0,
      location_string: '<string>',
      name: '<string>',
      starred: false
    },
    paired_end_filename: '<string>',
    project: {__DOLLAR_REF__: '/api/v1/projects/a1b2c3d4e5f67890'},
    sample_id: '<string>',
    size: 1,
    tags: [],
    upload_type: 'standard'
  })
};

fetch('https://app.onecodex.com/api/v1/samples/init_upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.onecodex.com/api/v1/samples/init_upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filename' => '<string>',
    'external_sample_id' => '<string>',
    'interleaved' => true,
    'metadata' => [
        'custom' => [
                
        ],
        'date_collected' => '2023-11-07T05:31:56Z',
        'date_sequenced' => '2023-11-07T05:31:56Z',
        'description' => '<string>',
        'external_sample_id' => 'LIMS-2024-00123',
        'location_lat' => 0,
        'location_lon' => 0,
        'location_string' => '<string>',
        'name' => '<string>',
        'starred' => false
    ],
    'paired_end_filename' => '<string>',
    'project' => [
        '__DOLLAR_REF__' => '/api/v1/projects/a1b2c3d4e5f67890'
    ],
    'sample_id' => '<string>',
    'size' => 1,
    'tags' => [
        
    ],
    'upload_type' => 'standard'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.onecodex.com/api/v1/samples/init_upload"

	payload := strings.NewReader("{\n  \"filename\": \"<string>\",\n  \"external_sample_id\": \"<string>\",\n  \"interleaved\": true,\n  \"metadata\": {\n    \"custom\": {},\n    \"date_collected\": \"2023-11-07T05:31:56Z\",\n    \"date_sequenced\": \"2023-11-07T05:31:56Z\",\n    \"description\": \"<string>\",\n    \"external_sample_id\": \"LIMS-2024-00123\",\n    \"location_lat\": 0,\n    \"location_lon\": 0,\n    \"location_string\": \"<string>\",\n    \"name\": \"<string>\",\n    \"starred\": false\n  },\n  \"paired_end_filename\": \"<string>\",\n  \"project\": {\n    \"__DOLLAR_REF__\": \"/api/v1/projects/a1b2c3d4e5f67890\"\n  },\n  \"sample_id\": \"<string>\",\n  \"size\": 1,\n  \"tags\": [],\n  \"upload_type\": \"standard\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.onecodex.com/api/v1/samples/init_upload")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"<string>\",\n  \"external_sample_id\": \"<string>\",\n  \"interleaved\": true,\n  \"metadata\": {\n    \"custom\": {},\n    \"date_collected\": \"2023-11-07T05:31:56Z\",\n    \"date_sequenced\": \"2023-11-07T05:31:56Z\",\n    \"description\": \"<string>\",\n    \"external_sample_id\": \"LIMS-2024-00123\",\n    \"location_lat\": 0,\n    \"location_lon\": 0,\n    \"location_string\": \"<string>\",\n    \"name\": \"<string>\",\n    \"starred\": false\n  },\n  \"paired_end_filename\": \"<string>\",\n  \"project\": {\n    \"__DOLLAR_REF__\": \"/api/v1/projects/a1b2c3d4e5f67890\"\n  },\n  \"sample_id\": \"<string>\",\n  \"size\": 1,\n  \"tags\": [],\n  \"upload_type\": \"standard\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.onecodex.com/api/v1/samples/init_upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filename\": \"<string>\",\n  \"external_sample_id\": \"<string>\",\n  \"interleaved\": true,\n  \"metadata\": {\n    \"custom\": {},\n    \"date_collected\": \"2023-11-07T05:31:56Z\",\n    \"date_sequenced\": \"2023-11-07T05:31:56Z\",\n    \"description\": \"<string>\",\n    \"external_sample_id\": \"LIMS-2024-00123\",\n    \"location_lat\": 0,\n    \"location_lon\": 0,\n    \"location_string\": \"<string>\",\n    \"name\": \"<string>\",\n    \"starred\": false\n  },\n  \"paired_end_filename\": \"<string>\",\n  \"project\": {\n    \"__DOLLAR_REF__\": \"/api/v1/projects/a1b2c3d4e5f67890\"\n  },\n  \"sample_id\": \"<string>\",\n  \"size\": 1,\n  \"tags\": [],\n  \"upload_type\": \"standard\"\n}"

response = http.request(request)
puts response.read_body

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

POST

api

samples

init_upload

POST samples instances_init_upload

curl --request POST \
  --url https://app.onecodex.com/api/v1/samples/init_upload \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "filename": "<string>",
  "external_sample_id": "<string>",
  "interleaved": true,
  "metadata": {
    "custom": {},
    "date_collected": "2023-11-07T05:31:56Z",
    "date_sequenced": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "external_sample_id": "LIMS-2024-00123",
    "location_lat": 0,
    "location_lon": 0,
    "location_string": "<string>",
    "name": "<string>",
    "starred": false
  },
  "paired_end_filename": "<string>",
  "project": {
    "__DOLLAR_REF__": "/api/v1/projects/a1b2c3d4e5f67890"
  },
  "sample_id": "<string>",
  "size": 1,
  "tags": [],
  "upload_type": "standard"
}
'

import requests

url = "https://app.onecodex.com/api/v1/samples/init_upload"

payload = {
    "filename": "<string>",
    "external_sample_id": "<string>",
    "interleaved": True,
    "metadata": {
        "custom": {},
        "date_collected": "2023-11-07T05:31:56Z",
        "date_sequenced": "2023-11-07T05:31:56Z",
        "description": "<string>",
        "external_sample_id": "LIMS-2024-00123",
        "location_lat": 0,
        "location_lon": 0,
        "location_string": "<string>",
        "name": "<string>",
        "starred": False
    },
    "paired_end_filename": "<string>",
    "project": { "__DOLLAR_REF__": "/api/v1/projects/a1b2c3d4e5f67890" },
    "sample_id": "<string>",
    "size": 1,
    "tags": [],
    "upload_type": "standard"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    filename: '<string>',
    external_sample_id: '<string>',
    interleaved: true,
    metadata: {
      custom: {},
      date_collected: '2023-11-07T05:31:56Z',
      date_sequenced: '2023-11-07T05:31:56Z',
      description: '<string>',
      external_sample_id: 'LIMS-2024-00123',
      location_lat: 0,
      location_lon: 0,
      location_string: '<string>',
      name: '<string>',
      starred: false
    },
    paired_end_filename: '<string>',
    project: {__DOLLAR_REF__: '/api/v1/projects/a1b2c3d4e5f67890'},
    sample_id: '<string>',
    size: 1,
    tags: [],
    upload_type: 'standard'
  })
};

fetch('https://app.onecodex.com/api/v1/samples/init_upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.onecodex.com/api/v1/samples/init_upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'filename' => '<string>',
    'external_sample_id' => '<string>',
    'interleaved' => true,
    'metadata' => [
        'custom' => [
                
        ],
        'date_collected' => '2023-11-07T05:31:56Z',
        'date_sequenced' => '2023-11-07T05:31:56Z',
        'description' => '<string>',
        'external_sample_id' => 'LIMS-2024-00123',
        'location_lat' => 0,
        'location_lon' => 0,
        'location_string' => '<string>',
        'name' => '<string>',
        'starred' => false
    ],
    'paired_end_filename' => '<string>',
    'project' => [
        '__DOLLAR_REF__' => '/api/v1/projects/a1b2c3d4e5f67890'
    ],
    'sample_id' => '<string>',
    'size' => 1,
    'tags' => [
        
    ],
    'upload_type' => 'standard'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.onecodex.com/api/v1/samples/init_upload"

	payload := strings.NewReader("{\n  \"filename\": \"<string>\",\n  \"external_sample_id\": \"<string>\",\n  \"interleaved\": true,\n  \"metadata\": {\n    \"custom\": {},\n    \"date_collected\": \"2023-11-07T05:31:56Z\",\n    \"date_sequenced\": \"2023-11-07T05:31:56Z\",\n    \"description\": \"<string>\",\n    \"external_sample_id\": \"LIMS-2024-00123\",\n    \"location_lat\": 0,\n    \"location_lon\": 0,\n    \"location_string\": \"<string>\",\n    \"name\": \"<string>\",\n    \"starred\": false\n  },\n  \"paired_end_filename\": \"<string>\",\n  \"project\": {\n    \"__DOLLAR_REF__\": \"/api/v1/projects/a1b2c3d4e5f67890\"\n  },\n  \"sample_id\": \"<string>\",\n  \"size\": 1,\n  \"tags\": [],\n  \"upload_type\": \"standard\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.onecodex.com/api/v1/samples/init_upload")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"<string>\",\n  \"external_sample_id\": \"<string>\",\n  \"interleaved\": true,\n  \"metadata\": {\n    \"custom\": {},\n    \"date_collected\": \"2023-11-07T05:31:56Z\",\n    \"date_sequenced\": \"2023-11-07T05:31:56Z\",\n    \"description\": \"<string>\",\n    \"external_sample_id\": \"LIMS-2024-00123\",\n    \"location_lat\": 0,\n    \"location_lon\": 0,\n    \"location_string\": \"<string>\",\n    \"name\": \"<string>\",\n    \"starred\": false\n  },\n  \"paired_end_filename\": \"<string>\",\n  \"project\": {\n    \"__DOLLAR_REF__\": \"/api/v1/projects/a1b2c3d4e5f67890\"\n  },\n  \"sample_id\": \"<string>\",\n  \"size\": 1,\n  \"tags\": [],\n  \"upload_type\": \"standard\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.onecodex.com/api/v1/samples/init_upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filename\": \"<string>\",\n  \"external_sample_id\": \"<string>\",\n  \"interleaved\": true,\n  \"metadata\": {\n    \"custom\": {},\n    \"date_collected\": \"2023-11-07T05:31:56Z\",\n    \"date_sequenced\": \"2023-11-07T05:31:56Z\",\n    \"description\": \"<string>\",\n    \"external_sample_id\": \"LIMS-2024-00123\",\n    \"location_lat\": 0,\n    \"location_lon\": 0,\n    \"location_string\": \"<string>\",\n    \"name\": \"<string>\",\n    \"starred\": false\n  },\n  \"paired_end_filename\": \"<string>\",\n  \"project\": {\n    \"__DOLLAR_REF__\": \"/api/v1/projects/a1b2c3d4e5f67890\"\n  },\n  \"sample_id\": \"<string>\",\n  \"size\": 1,\n  \"tags\": [],\n  \"upload_type\": \"standard\"\n}"

response = http.request(request)
puts response.read_body

{
  "sample_id": "<string>",
  "upload_url": "<string>",
  "additional_fields": {},
  "fallback_options": {},
  "paired_end_additional_fields": {},
  "paired_end_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 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 or Python requests is:

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

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

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

# Returns a 201 response

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

# Start the upload
resp = requests.post('https://app.onecodex.com/api/v1/init_upload',
                     json={'filename': 'HiSeq_accuracy.fa',
                           'size': os.path.getsize('HiSeq_accuracy.fa')},
                     auth=(os.getenv('ONE_CODEX_API_KEY'), '')
                    ).json()

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

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

Authorizations

X-API-Key

string

header

required

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.

Pattern: ^[\w\.]+[\w\-\.\[\]\{\} ]*\.[\w\.]+$

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

InlineMetadata · object | null

An optional metadata object to be added to the sample.

Show child attributes

paired_end_filename

string | null

Optional filename for paired end uploads.

Pattern: ^[\w\.]+[\w\-\.\[\]\{\} ]*\.[\w\.]+$

project

projects · object | null

An optional project into which to upload the sample.

Show child attributes

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 >= 0

Response

200 - application/json

sample_id

string

required

The sample ID. Use to confirm the upload.

upload_url

string

required

Object storage location to POST the file to.

additional_fields

Additional Fields · object

Additional fields to include in the object storage POST request.

fallback_options

Fallback Options · object | null

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

paired_end_additional_fields

Paired End Additional Fields · object | 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).

Uploads Overview Confirming an Upload

API Basics

Samples

Projects

Metadata & Tags

Analyses

Jobs

Documents

Webhooks & Events

Users & Account

Sequencing

Performing the actual upload – “standard” upload type

Authorizations

Body

Response

​Performing the actual upload – “standard” upload type

Authorizations

Body

Response

Performing the actual upload – “standard” upload type