Starting a Document Upload

Deprecated in favour of init_multipart_upload

curl --request POST \
  --url https://app.onecodex.com/api/v1/documents/init_upload \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "filename": "<string>",
  "size": 2
}
'

import requests

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

payload = {
    "filename": "<string>",
    "size": 2
}
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>', size: 2})
};

fetch('https://app.onecodex.com/api/v1/documents/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/documents/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>',
    'size' => 2
  ]),
  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/documents/init_upload"

	payload := strings.NewReader("{\n  \"filename\": \"<string>\",\n  \"size\": 2\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/documents/init_upload")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"<string>\",\n  \"size\": 2\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.onecodex.com/api/v1/documents/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  \"size\": 2\n}"

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

{
  "additional_fields": {},
  "document_id": "<string>",
  "upload_url": "<string>"
}

POST

api

documents

init_upload

Deprecated in favour of init_multipart_upload

curl --request POST \
  --url https://app.onecodex.com/api/v1/documents/init_upload \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "filename": "<string>",
  "size": 2
}
'

import requests

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

payload = {
    "filename": "<string>",
    "size": 2
}
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>', size: 2})
};

fetch('https://app.onecodex.com/api/v1/documents/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/documents/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>',
    'size' => 2
  ]),
  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/documents/init_upload"

	payload := strings.NewReader("{\n  \"filename\": \"<string>\",\n  \"size\": 2\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/documents/init_upload")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filename\": \"<string>\",\n  \"size\": 2\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.onecodex.com/api/v1/documents/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  \"size\": 2\n}"

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

{
  "additional_fields": {},
  "document_id": "<string>",
  "upload_url": "<string>"
}

Start an upload by POSTing 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 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
# 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"

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'), ''))

Authorizations

X-API-Key

string

header

required

Body

application/json

filename

string

required

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

size

integer

required

The size of the file in bytes.

Required range: x >= 1

Response

200 - application/json

additional_fields

Additional Fields · object

required

Additional fields to include in the upload.

document_id

string

required

The document_id of the uploaded document.

upload_url

string

required

The URL to POST the document to.

Uploading Documents Overview Confirming an Upload

API Basics

Samples

Projects

Metadata & Tags

Analyses

Jobs

Documents

Webhooks & Events

Users & Account

Sequencing

Performing the actual upload

Authorizations

Body

Response

​Performing the actual upload

Authorizations

Body

Response

Performing the actual upload