API

Authentication

All routes require Basic access authentication over HTTPS unless otherwise noted.

Request and response bodies

All routes which receive request bodies expect a Content-Type of application/json unless otherwise noted.

All request bodies must be encoded with UTF-8. All response bodies are encoded with UTF-8 unless explicitly declared otherwise by a Content-Type header.

Status codes

All routes use standard HTTP status codes.

If the Content-Type of a 400 Bad Request response is application/json, then the body will be a JSON object with at least the key error. Additional keys may provide more details.

Routes

POST /v1/receiving/enrollment

Stores the request data as an enrollment document in a receiving area of the study database. Accepts any JSON object.

POST /v1/receiving/presence-absence

Stores the request data as presence/absence calls in a receiving area of the study database. Accepts any JSON object.

POST /v1/receiving/sequence-read-set

Stores the request data as a sequence read set document in a receiving area of the study database.

By convention, the body of the request should be a JSON object like the following:

      {
          "source": {
            "sample": "20e1d4a2",
            ...
          },
          "reads": [
            "https://server/path/to/reads_L001_R1_001.fastq.gz",
            "https://server/path/to/reads_L001_R2_001.fastq.gz",
            ...
          ]
      }
      

POST /v1/receiving/redcap-det

Stores the request data from a REDCap data entry trigger (DET) in a receiving area of the study database. Accepts any URL-encoded form data.

POST /v1/receiving/fhir

Stores the request data as a FHIR document in a receiving area of the study database. This route expects a Content-Type of application/fhir+json

POST /v1/receiving/consensus-genome

Stores the request data as a consensus genome document in a receiving area of the study database.

POST /v1/receiving/manifest/incident

Stores the request data as a manifest incident document in a receiving area of the study database. The body of the request should be a JSON document with the following format:

        {
            "collection": "2e99a5f3",
            "failure_type": "Unused kit",
            "incident_date": "2021-01-01",
            "swab_type": "ans",
            "corrective_action": "discarded",
            "collection_matrix": "dry"
        }
      

GET /v1/warehouse/identifier/<id>

Retrieve metadata about an identifier id. id may be a full UUID or shortened barcode.

GET /v1/warehouse/identifier-sets

Retrieve metadata about all identifier sets.

GET /v1/warehouse/identifier-sets/<name>

Retrieve metadata about an identifier set name.

PUT /v1/warehouse/identifier-sets/<name>

Make a new identifier set name. Idempotent if the set already exists. Optional description parameter may be provided. A use parameter is required for new sets and is optional if only updating description on an existing set.

GET /v1/warehouse/sample/<barcode>

Retrieve metadata about a sample record by sample barcode.

GET /v1/warehouse/sample?collection_barcode=<barcode>

Retrieve metadata about a sample record by collection barcode.

POST /v1/warehouse/sample

Insert or update a sample record.

The body of the request should be a JSON object with the following format:

        {
            "sample_id": "20e1d4a2",
            "collection_id": "2e99a5f3",
            "sample_origin": "uw-reopening",
            "collection_date": "2021-01-01",
            "swab_site": "uw_club",
            "clia_id": "9f8a58a6",
            "received_date": "2021-01-01",
            "aliquot_a":"123456789",
            "aliquot_b":"987654321",
            "aliquot_c":"135792468",
            "aliquoted_date": "2021-01-01",
            "rack_a":"TS01234567",
            "rack_b":"TS07654321",
            "rack_c":"TS08912345",
            "rack_a_nickname":"COV2-123A",
            "rack_b_nickname":"COV2-321B",
            "rack_c_nickname":"COV2-213C",
            "notes": "sample notes",
            "swab_type": "ans",
            "collection_matrix": "dry"
        }
        

GET /v1/warehouse/identifier-set-uses

Retrieve metadata about all identifier set uses.

POST /v1/verification/barcode-uses/verify

Verify a list of barcodes and use types for each.

By convention, the body of the request should be a JSON array of objects like the following:

        [
            {
              "barcode": "20e1d4a2",
              "use": "sample"
            },
            ...
        ]
        

Legacy Routes

These routes have been deprecated but continue to be supported (for now).

POST /enrollment

Stores the request data as an enrollment document in a receiving area of the study database. Accepts any JSON object.

POST /presence-absence

Stores the request data as presence/absence calls in a receiving area of the study database. Accepts any JSON object.

POST /sequence-read-set

Stores the request data as a sequence read set document in a receiving area of the study database.

By convention, the body of the request should be a JSON object like the following:

{
  "source": {
    "sample": "20e1d4a2",
    ...
  },
  "reads": [
    "https://server/path/to/reads_L001_R1_001.fastq.gz",
    "https://server/path/to/reads_L001_R2_001.fastq.gz",
    ...
  ]
}