---
title: "POST samples instances_init_upload"
method: POST
path: "/api/v1/samples/init_upload"
---

# POST samples instances_init_upload

`POST /api/v1/samples/init_upload`

## Request body

- object
  - `external_sample_id` string, nullable — 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` 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.
  - `interleaved` boolean, nullable — Whether the file is interleaved (true) or not (false).
  - `metadata` object, nullable — An optional metadata object to be added to the sample.
    - `custom` object, nullable — 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` string, date-time, nullable — Timestamp for when the sample was collected.
    - `date_sequenced` string, date-time, nullable — Timestamp for when the sample was sequenced.
    - `description` string, nullable
    - `external_sample_id` string, nullable — An arbitrary external sample ID, e.g., an ID in a LIMS. Up to 60 characters.
    - `library_type` 'WGS' | 'Targeted/16S' | 'Other', nullable — Allowed types of SampleMetadata.library_type. Also used to populate form dropdown in the front-end
    - `location_lat` number, nullable — 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` number, nullable — The longitude `(-180.0-180.0)` of the sample location.
    - `location_string` string, nullable
    - `name` string, nullable
    - `platform` '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', nullable — Allowed values of SampleMetadata.platform.
    - `sample_type` 'Isolate' | 'Metagenomic' | 'Other', nullable — Allowed values for SampleMetadata.sample_type. Used to populate values in the front-end dropdown
    - `starred` boolean, nullable — Whether the sample has been starred by the user within the One Codex web application.
  - `paired_end_filename` string, nullable — Optional filename for paired end uploads.
  - `project` object, nullable — An optional project into which to upload the sample.
    - `__DOLLAR_REF__` string, uri
  - `sample_id` string, nullable — An optional sample ID to match against pre-uploaded samples. Returns a 400 if no matching sample is found.
  - `size` integer, nullable — The size of the file in bytes.
  - `tags` object[] — An array of tags to be added to the sample.
    - `name` string, required — The tag label or name. Name must be 30 characters or fewer.
  - `upload_type` 'standard' — The type of upload to initiate. Currently only standard uploads are supported via the init_upload route.

## Response `200`

OK

- object
  - `additional_fields` object — Additional fields to include in the object storage POST request.
  - `fallback_options` object, nullable — Fallback options for the upload. Please contact support for help as needed.
  - `paired_end_additional_fields` object, nullable — Additional fields to include in the object storage POST request for the paired end file (optional).
  - `paired_end_upload_url` string, nullable — Object storage location to POST the paired end file to (optional).
  - `sample_id` string, required — The sample ID. Use to confirm the upload.
  - `upload_url` string, required — Object storage location to POST the file to.

---

[API](https://skmtc.net/onecodex/apis/one-codex-api-v1.md) · [All operations](https://skmtc.net/onecodex/apis/one-codex-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onecodex/one-codex-api-v1/versions/fe9d9bfc8a6a/schema)