> ## Documentation Index > Fetch the complete documentation index at: https://developer.onecodex.com/llms.txt > Use this file to discover all available pages before exploring further. # Starting an Upload Start an upload by `POST`ing 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](https://httpie.org) or Python requests is: ```sh httpie theme={null} # 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" ``` ```python Python theme={null} # 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'), '')) ``` ## OpenAPI ````yaml POST /api/v1/samples/init_upload openapi: 3.0.0 info: title: One Codex API (v1) description: >- The One Codex API (v1) -- programmatic access to One Codex's suite of microbial genomics data storage, analysis, and query tools. version: v1 servers: - url: https://app.onecodex.com security: - apiKeyAuth: [] paths: /api/v1/samples/init_upload: post: summary: POST samples init_upload operationId: post_samples_init_upload requestBody: content: application/json: schema: type: object properties: external_sample_id: type: string nullable: true description: >- An optional external sample ID (see the Metadata resource) to match against pre-uploaded samples. Returns a 400 if no matching sample is found. filename: type: string pattern: ^[\w\.]+[\w\-\.\[\]\(\)\{\} ]*\.[\w\.]+$ description: >- 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. interleaved: type: boolean nullable: true description: Whether the file is interleaved (true) or not (false). metadata: type: object description: A metadata object. properties: custom: type: object default: {} description: >- 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"}` date_collected: type: string nullable: true format: date-time description: Timestamp for when the sample was collected. date_sequenced: type: string nullable: true format: date-time description: Timestamp for when the sample was sequenced. description: type: string nullable: true external_sample_id: type: string nullable: true maxLength: 60 description: >- An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters. library_type: type: string nullable: true enum: - WGS - Targeted/16S - Other - null description: An enum with the sample library type. location_lat: type: number nullable: true minimum: -90 maximum: 90 description: >- 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. location_lon: type: number nullable: true minimum: -180 maximum: 180 description: The longitude `(-180.0-180.0)` of the sample location. location_string: type: string nullable: true maxLength: 255 name: type: string nullable: true maxLength: 255 platform: type: string nullable: true enum: - 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 - null description: An enum with the name of the sequencing platform. sample_type: type: string nullable: true enum: - Isolate - Metagenomic - Other - null description: An enum with the sample type. starred: type: boolean default: false description: >- Whether the sample has been starred by the user within the One Codex web application. paired_end_filename: type: string nullable: true pattern: ^[\w\.]+[\w\-\.\[\]\(\)\{\} ]*\.[\w\.]+$ description: Optional filename for paired end uploads. project: type: object description: An optional project into which to upload the sample. anyOf: - type: object properties: $ref: 5c1e5594-ef80-45a5-8202-08f6859d3230 - type: string nullable: true maxLength: 16 sample_id: type: string nullable: true description: >- An optional sample ID to match against pre-uploaded samples. Returns a 400 if no matching sample is found. size: type: integer nullable: true minimum: 1 description: The size of the file in bytes. tags: type: array default: [] items: type: object description: An array of tag objects. properties: name: type: string maxLength: 30 description: >- The tag label or name. Name must be 30 characters or fewer. required: - name upload_type: type: string enum: - standard default: standard description: >- The type of upload to initiate. Currently only standard uploads are supported via the init_upload route. required: - filename required: true responses: '200': description: Successful operation content: application/json: schema: type: object properties: additional_fields: type: string nullable: true description: >- Additional fields to include in the object storage POST request. items: type: object fallback_options: type: string nullable: true description: >- Fallback options for the upload. Please contact support for help as needed. items: type: object paired_end_additional_fields: type: string nullable: true description: >- Additional fields to include in the object storage POST request for the paired end file (optional). items: type: object paired_end_upload_url: type: string nullable: true description: >- Object storage location to POST the paired end file to (optional). sample_id: type: string description: The sample ID. Use to confirm the upload. upload_url: type: string description: Object storage location to POST the file to. components: securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key ````