> ## 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.1.0 info: description: >- The One Codex API (v1) -- programmatic access to One Codex's suite of microbial genomics data storage, analysis, and query tools. title: One Codex API (v1) version: v1 servers: - url: https://app.onecodex.com security: - apiKeyAuth: [] paths: /api/v1/samples/init_upload: post: summary: POST samples instances_init_upload operationId: post_samples_instances_init_upload requestBody: content: application/json: schema: properties: external_sample_id: anyOf: - type: string - type: 'null' default: null 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. title: External Sample Id filename: 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. pattern: ^[\w\.]+[\w\-\.\[\]\(\)\{\} ]*\.[\w\.]+$ title: Filename type: string interleaved: anyOf: - type: boolean - type: 'null' default: null description: Whether the file is interleaved (true) or not (false). title: Interleaved metadata: anyOf: - properties: custom: anyOf: - additionalProperties: true type: object - type: 'null' 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"}` title: Custom date_collected: anyOf: - format: date-time type: string - type: 'null' default: null description: Timestamp for when the sample was collected. title: Date Collected date_sequenced: anyOf: - format: date-time type: string - type: 'null' default: null description: Timestamp for when the sample was sequenced. title: Date Sequenced description: anyOf: - type: string - type: 'null' default: null title: Description external_sample_id: anyOf: - type: string - type: 'null' default: null description: >- An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters. example: LIMS-2024-00123 title: External Sample Id library_type: anyOf: - description: >- Allowed types of SampleMetadata.library_type. Also used to populate form dropdown in the front-end enum: - WGS - Targeted/16S - Other title: SequencingLibraryType type: string - type: 'null' default: null description: An enum with the sample library type. location_lat: anyOf: - maximum: 90 minimum: -90 type: number - type: 'null' default: null 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. title: Location Lat location_lon: anyOf: - maximum: 180 minimum: -180 type: number - type: 'null' default: null description: >- The longitude `(-180.0-180.0)` of the sample location. title: Location Lon location_string: anyOf: - maxLength: 255 type: string - type: 'null' default: null title: Location String name: anyOf: - maxLength: 255 type: string - type: 'null' default: null title: Name platform: anyOf: - description: Allowed values of SampleMetadata.platform. 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 title: SequencingPlatform type: string - type: 'null' default: null description: An enum with the name of the sequencing platform. sample_type: anyOf: - description: >- Allowed values for SampleMetadata.sample_type. Used to populate values in the front-end dropdown enum: - Isolate - Metagenomic - Other title: SequencingSampleType type: string - type: 'null' default: null description: An enum with the sample type. starred: anyOf: - type: boolean - type: 'null' default: false description: >- Whether the sample has been starred by the user within the One Codex web application. title: Starred title: InlineMetadata type: object - type: 'null' default: null description: An optional metadata object to be added to the sample. paired_end_filename: anyOf: - pattern: ^[\w\.]+[\w\-\.\[\]\(\)\{\} ]*\.[\w\.]+$ type: string - type: 'null' default: null description: Optional filename for paired end uploads. title: Paired End Filename project: anyOf: - properties: __DOLLAR_REF__: example: /api/v1/projects/a1b2c3d4e5f67890 format: uri pattern: ^/api/v1/projects/[a-f0-9]{16}$ type: string title: projects type: object - type: 'null' default: null description: An optional project into which to upload the sample. title: Project sample_id: anyOf: - type: string - type: 'null' default: null description: >- An optional sample ID to match against pre-uploaded samples. Returns a 400 if no matching sample is found. title: Sample Id size: anyOf: - minimum: 0 type: integer - type: 'null' default: null description: The size of the file in bytes. title: Size tags: default: [] description: An array of tags to be added to the sample. items: properties: name: description: >- The tag label or name. Name must be 30 characters or fewer. maxLength: 30 title: Name type: string required: - name title: InlineTag type: object title: Tags type: array upload_type: const: standard default: standard description: >- The type of upload to initiate. Currently only standard uploads are supported via the init_upload route. title: Upload Type type: string required: - filename title: SampleInitUploadSchema type: object required: true responses: '200': content: application/json: schema: properties: additional_fields: additionalProperties: true default: {} description: >- Additional fields to include in the object storage POST request. title: Additional Fields type: object fallback_options: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: >- Fallback options for the upload. Please contact support for help as needed. title: Fallback Options paired_end_additional_fields: anyOf: - additionalProperties: true type: object - type: 'null' default: {} description: >- Additional fields to include in the object storage POST request for the paired end file (optional). title: Paired End Additional Fields paired_end_upload_url: anyOf: - type: string - type: 'null' default: null description: >- Object storage location to POST the paired end file to (optional). title: Paired End Upload Url sample_id: description: The sample ID. Use to confirm the upload. title: Sample Id type: string upload_url: description: Object storage location to POST the file to. title: Upload Url type: string required: - sample_id - upload_url title: SampleInitUploadResponse type: object description: OK components: securitySchemes: apiKeyAuth: in: header name: X-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.