Genome Files Service API

• Basic Usage
• Genome Files
• Uploads
• Scan Jobs

Basic Usage

There are 5 steps to process a file:

1. Create a genome file using the profile id (POST /file/
2. Create a pre-signed URL using the genome file id (POST /upload-url/)
3. Upload the file to the pre-signed URL
4. Notify the service the upload is complete (DELETE /upload-url/:id/)
5. Start a scan job to process the file (POST /file/:id/scan/)

Genome Files

Endpoints:

1. /file/
2. /file-processing-service/version/

Most tasks use the /file/ endpoint:

• POST creates a genome file for a given profile (step 1)

  • Payload:

    • profile id (required)
    • upload_provider (optional)

  • Response:

    • id field will be used for all other endpoints

• GET returns a list of all genome files associated with the user’s account

  • No request payload

• GET describe a specific genome file

  • Path: /file/{genome-file-id}/

• GET download the genome file

  • Path: /file/{genome-file-id}/download/

The second endpoint returns the current file-processing version.

Uploads

There are 3 endpoints for uploads:

1. /upload-url/
2. /upload-raw-reads/
3. /bulk-upload/

Most users will only use the /upload-url/ endpoint. The /upload-raw-reads/ endpoint is only used for large file pairs containing raw sequencing data.

The /bulk-upload/ endpoint is used for uploading an archive containing multiple genome files and a file manifest linking each genome file to a profile or sample id.

In general, the endpoints are used the same way:

• POST create pre-signed URLs for uploading files (step 2)

  • Request payload:

    • genome_file ID in /file/response (required for /upload-url/ and /upload-raw-reads/)
    • filename the local path of the file being uploaded (required)
    • filename_reverse (only used for /upload-raw-reads/)

  • Response:

    • id the upload id is used to complete the upload
    • upload_url field contains pre-signed URL for uploading

• DELETE complete the file upload (step 4)

  • Path:
    • /upload-url/{upload-id}/
    • /upload-raw-reads/{upload-id}/
    • /bulk-upload/{upload-id}/

Additional guidance for /upload-raw-reads/:

• The size limit for each file is 5 GB.
• Files should be compressed with gzip or bgzip.
• The large files required for raw sequencing reads can sometimes result in interrupted uploads. The response payload for the DELETE endpoint contains the sizes of the uploaded files, enabling you to confirm that your entire file was uploaded.
• If you have not previously uploaded sequencing reads to our service, contact your representative to confirm that we have added your sequencing method to our pipeline.

Additional guidance for /bulk-upload/:

• We accept zip and compressed tar archives.
• Your archive must contain a file with manifest in the filename.
  • Most users will need only two columns in their manifest:
    • filename: the path of each file in the archive (required)
    • profile id: the UUID of the SelfDecode profile (required)
  • If uploading sequencing lab results from DNA samples registered with the /product/dna-sample/ endpoint, your manifest will need three columns:
    • filename: the path of each file in the archive (required)
    • sample id: the ID of the registered DNA kit
    • call rate: the call rate of the sample generated during processing
• After the upload finishes processing, a GET request with the upload id will return the status of the upload and the genome file UUIDs of the created genome files.
• Scan jobs will start automatically.

Scan Jobs

Start a scan job using the genome-file endpoint:

• POST start processing a genome file

  • Path: /file/{genome-file-id}/scan/

/scan-job/ (deprecated)

• POST start processing a genome file

  • Request payload:

    • genome_file (required)

---