POST
/
api
/
v1
/
documents
/
init_upload
{
  "additional_fields": "<string>",
  "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"

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
Successful operation
​
additional_fields
string | null

Additional fields to include in the upload.

​
document_id
string

The document_id of the uploaded document.

​
upload_url
string

The URL to POST the document to.