{"openapi":"3.0.3","info":{"title":"Upload Genomic Data","description":"## Overview\n\nThis page describes the technical details of the Upload Genomic Data (UGD) service, including available endpoints. For a high-level overview of the service, see the [Upload Genomic Data service page](https://digital.nhs.uk/services/genomic-data/upload-genomic-data-service?key=3gjQjuQhN7E1nzAcGRZ1Jt5dpSHGrQ3Gye0D7vH82OM0Ov97BWwRvpY7PTbCBkx6).\n\nUse this API to securely upload patient genomic data for downstream processing by NHS Genomic Medicine Service (GMS) applications.\n\nUploading genomic data occurs in **six stages**:\n\n1. Verify that genomic sequence data is expected\n2. Make an upload request\n3. Upload the data\n4. Register the data\n5. Provide associated metadata\n6. Update the ServiceRequest to reference uploaded specimens  \n\n---\n\n### Stage 1: Verify that genomic sequence data is expected\n\nBefore uploading any genomic sequence data, clients **must confirm that Genomics England (GEL) is expecting data for the referral**.\n\nClients should issue a `GET` request to the `/fhir/r4/ServiceRequest` endpoint to locate a `ServiceRequest` that matches the NGIS `referral_id`. The matching `ServiceRequest` must reference the relevant NGIS `participant_id` in **either**:\n\n- `ServiceRequest.subject` — representing the **proband**, or  \n- `ServiceRequest.supportingInfo` — representing **family members** associated with the referral.\n\nIf no matching `ServiceRequest` is found, or if the participant is not referenced in either field, **clients must not proceed with data upload**.\n\n[Try Search for ServiceRequest endpoint](#get-/fhir/r4/ServiceRequest)\n\n---\n\n### Stage 2: Make an upload request\n\nSend a `POST` request to the `/gel/drsupload/v1/upload-request` endpoint with metadata describing the files to be uploaded.\n\nThe response will include upload locations and the credentials required to upload the data.\n\n#### Upload session lifetime\n\nFor a given upload request, clients have **up to 1 hour** from the time upload locations and credentials are issued to successfully upload **all files in that batch** to the locations provided.\n\nIf all files in the batch are not successfully uploaded within this time window, the upload request expires and the batch **MUST be retried** by starting a new upload request.\n\n[Try Upload Request endpoint](#post-/gel/drsupload/v1/upload-request)\n\n---\n\n### Stage 3: Upload the data\n\nUpload each file using the locations and temporary credentials returned in Stage 2.\n\nFor each file in the Stage 2 response:\n\n1. **Parse the access URL** from `upload_methods[0].access_url.url` to extract the location of where the data should be uploaded.\n2. **Extract the temporary credentials** from `upload_methods[0].credentials`.\n3. **Upload the file**.\n\n**Example using AWS SDK (Python boto3):**\n\nThe current UGD implementation uses [AWS S3](https://aws.amazon.com/s3/) for data storage.\n\nSee the [worked example](#worked-example-rare-disease-single-lane-upload) below for further information.\n\n**Note:** No API authentication token is required for Stage 3 — the temporary S3 credentials are sufficient. These credentials are scoped to the specific upload and expire after a limited time. For very large files (tens of GB), plan for uploads that may take longer than the APIM token lifetime; the token will be refreshed automatically when needed for Stage 4.\n\n#### Handling upload failures**\n\nIf an upload to the storage location (for example S3) fails or times out for a file, clients **MUST abandon the upload protocol for that file at Stage 3**.\n\nIn this scenario, clients **MUST restart the upload process from Stage 1** for the affected sample and obtain new upload locations and credentials.\n\nPartially uploaded or failed files **MUST NOT** be reused or registered.\n\n---\n\n### Stage 4: Register the data\n\nAfter uploading the data, send a `POST` request to the `/gel/drsupload/v1/register-objects` endpoint with candidate DRS objects.\n\nEach candidate **must include `access_methods`** containing the S3 `access_url` from the Stage 2 response. This tells DRS where the uploaded file is stored.\n\n#### Registration batch size limits\n\nThe `register-objects` operation accepts **up to 20 candidate DRS objects per request**.\n\nIf more than 20 uploaded files need to be registered, clients **MUST split registration across multiple Stage 4 requests**, each containing no more than 20 candidate objects.\n\nThis limit applies **only to the registration step** and does not restrict the number of files uploaded in Stages 2 and 3.\n\n```json\n{\n\"candidates\": [\n    {\n    \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n    \"size\": 31457280,\n    \"mime_type\": \"text/fastq\",\n    \"checksums\": [\n        { \"checksum\": \"a1b2c3d4e5f6...\", \"type\": \"sha-256\" }\n    ],\n    \"access_methods\": [\n        {\n        \"type\": \"s3\",\n        \"access_url\": {\n            \"url\": \"s3://gel-bucket/uploads/sample1_S1_L001_R1_001.fastq.gz\"\n        }\n        }\n    ]\n    }\n]\n}\n\n```\n\nA successful registration returns HTTP 201.\n\n[Try Register Objects endpoint](#post-/gel/drsupload/v1/register-objects)\n\n---\n\n### Stage 5: Provide associated metadata\n\nSend a `POST` request to the `/fhir/r4` endpoint containing a [FHIR transaction Bundle](https://build.fhir.org/bundle.html) that describes the uploaded files and their clinical context.\n\nFHIR (Fast Healthcare Interoperability Resources) metadata allows uploaded genomic data to be discovered and used by other NHS Genomic Medicine Service (GMS) applications.\n\nThe transaction Bundle must contain five resources for a single-lane upload:\n\n1. **Child Specimen** (type: wgs-data, sample category: e.g. germline, gel1001 sample state: e.g. blood_unsorted_edta) - references parent Specimen and ServiceRequest\n2. **Parent Specimen** (type: lab-sample) - identified by fluid-x tube number\n3. **Procedure** - sequencing run, linked to referral via basedOn\n4. **DocumentReference (Read1)** - FASTQ file, links to Read2 via relatesTo \"appends\"\n5. **DocumentReference (Read2)** - FASTQ file, links to Read1 via relatesTo \"transforms\"\n\nFor multi-lane samples, an additional DocumentReference pair is added per lane. All internal cross-references use `urn:uuid:` format.\n\n**DRS object identifiers used in DocumentReference**\n\nEach DocumentReference in the transaction Bundle **MUST reference the DRS object created during Stage 4 (registration)**.\n\nClients **MUST NOT** use the temporary object identifiers returned from Stage 2 (`upload-request`) in DocumentReference content blocks.\n\n#### Specimen extensions\n\nThe `wgs-data` child Specimen must be the first entry in the transaction Bundle, as its server-assigned ID (returned in the response) is needed for Stage 6.\n\nThe UK Core Sample Category extension (Extension-UKCore-SampleCategory) MUST be present on all Specimen resources in the transaction Bundle, including both the `wgs-data` child Specimen and the parent `lab-sample` Specimen.\n\nThe GEL primary sample state extension (gel1001-primary-sample-state) MUST be present on the `wgs-data` child Specimen and MUST NOT be supplied on the parent lab-sample Specimen.\n\nFor details of the values that can go into the \"gel1001-primary-sample-state\" of the `wgs-data` child Specimen please refer to the [\"NGIS Sample Specification\"](https://future.nhs.uk/NHSgenomics/view?objectId=83469925). Specifically, see Column name \"primary_sample_state\" in the \"GEL1001 - fields\" tab.\n\nAll intra-Bundle cross-references use `urn:uuid:` format. References to existing resources (e.g. the ServiceRequest found in Stage 1) use the standard `ResourceType/{id}` format.\n\n**Extracting the Specimen ID from the response:** The response is a transaction-response Bundle. Each entry has a `response.location` header in the format `ResourceType/{id}/_history/{version}`. Extract the `{id}` from the **first Specimen entry** — this is the wgs-data child Specimen (because the Bundle places it first). This ID is what you need for Stage 6.\n\nExample response (abridged):\n\n```json\n{\n\"resourceType\": \"Bundle\",\n\"type\": \"transaction-response\",\n\"entry\": [\n    {\n    \"response\": {\n        \"status\": \"201 Created\",\n        \"location\": \"Specimen/aabbccdd-1122-3344-5566-778899aabbcc/_history/1\"\n    }\n    },\n    {\n    \"response\": {\n        \"status\": \"201 Created\",\n        \"location\": \"Specimen/eeff0011-2233-4455-6677-8899aabbccdd/_history/1\"\n    }\n    },\n    ...\n]\n}\n\n```\n\nThe first Specimen (`aabbccdd-1122-3344-5566-778899aabbcc`) is the wgs-data child. Record its ID for Stage 6.\n\n---\n\n### Stage 6: Update the ServiceRequest to reference uploaded specimens\n\nAfter all files have been successfully uploaded and registered, clients **must update** the originating `ServiceRequest` to reference the uploaded **wgs-data Specimen(s)**.\n\nSend a `PATCH` request to the `/fhir/r4/ServiceRequest/{id}` endpoint using the ServiceRequest ID from Stage 1. The request must use **Content-Type `application/json-patch+json`** (JSON Patch format per RFC 6902).\n\n**Only reference the wgs-data child Specimen** (not the lab-sample parent). This is the reference that triggers downstream bioinformatics pipelines.\n\nThe JSON Patch body depends on whether the ServiceRequest already has a `specimen` array (check the response from Stage 1):\n\n**If the ServiceRequest already has a `specimen` array** (for example, if a prior upload for the same referral has completed):\n\n```json\n[\n{\n    \"op\": \"add\",\n    \"path\": \"/specimen/-\",\n    \"value\": { \"reference\": \"Specimen/{wgs_data_specimen_id}\" }\n}\n]\n\n```\n\n**If the ServiceRequest has no `specimen` array** (first upload for this referral):\n\n```json\n[\n{\n    \"op\": \"add\",\n    \"path\": \"/specimen\",\n    \"value\": [{ \"reference\": \"Specimen/{wgs_data_specimen_id}\" }]\n}\n]\n\n```\n\nOnce all expected specimens have been referenced, **downstream processing of the genomic sequence data is automatically triggered** by the GEL WGS bioinformatics pipelines.\n\n[Try Update a FHIR ServiceRequest endpoint](#patch-/fhir/r4/ServiceRequest/-id-).\n\nRefer to the [Python client reference implementation](https://nhs-ngs.github.io/cgpclient/training/dwgs_upload/) for examples of using these endpoints to upload patient [FASTQ files](https://maq.sourceforge.net/fastq.shtml).\n\n### Data flow between stages\n\nEach stage produces outputs that subsequent stages depend on. Understanding this flow is essential.\n\n**Stage 1:**  GET /fhir/r4/ServiceRequest\n\n- service_request_id (FHIR resource ID, used in Stages 5 and 6)\n- Confirm participant is on the referral\n\n**Stage 2:**  POST /gel/drsupload/v1/upload-request\n\n- Returns temporary object identifiers and upload locations\n- These identifiers **MUST be used only to upload data and complete Stage 4**\n- They **MUST NOT** be referenced in FHIR metadata\n- Per file: upload_methods.access_url (URL, used in Stages 3 and 4)\n- Per file: upload_methods.credentials (temporary creds, used in Stage 3)\n\n**Stage 3:**  Upload files using credentials from Stage 2\n\n- No UGD API call - direct to storage location specified e.g S3 bucket\n\n**Stage 4:**  POST /gel/drsupload/v1/register-objects\n\n- Registers uploaded files as persistent GA4GH DRS objects\n- Accepts up to 20 candidate objects per request\n- Larger uploads must be registered across multiple requests\n- Returns **persistent GA4GH DRS object identifiers**\n- These identifiers **MUST be used in Stage 5 DocumentReference content blocks**\n- Requires: file metadata + access_methods (access_url from Stage 2)\n\n**Stage 5:**  POST /fhir/r4 (FHIR transaction Bundle)\n\n- Requires: service_request_id (Stage 1), persistent DRS object URIs from Stage 4, plus metadata (see worked example below)\n- Returns: Specimen IDs (extracted from response Bundle entry locations)\n\n**Stage 6:**  PATCH /fhir/r4/ServiceRequest/{id}\n\n- Requires: service_request_id (Stage 1), wgs-data Specimen ID (Stage 5)\n- Triggers downstream bioinformatics pipelines\n\n### File requirements\n\nFor each file to be uploaded, clients MUST provide:\n\n- The file size in bytes\n- A SHA‑256 checksum of the file contents, hex‑encoded using lowercase characters\n\n#### Recommended approaches\n\nClients should calculate file sizes and checksums directly from the final file artefact that will be uploaded.\n\nCommon approaches include:\n\n- Using operating system utilities or standard libraries to obtain the file size in bytes\n- Using a cryptographic hash function from a well‑tested standard library to generate a SHA‑256 checksum\n\nChecksums should be computed **before** requesting upload locations (Stage 2) and must not be recalculated against a modified or recompressed file.\n\n**MIME types:** Use the following MIME types based on file extension:\n\n| File extension                 | MIME type                  |\n| ------------------------------ | -------------------------- |\n| `.fastq.gz`, `.fq.gz`          | `text/fastq`               |\n| `.ora` (DRAGEN ORA-compressed) | `application/octet-stream` |\n\n### Performance and connectivity considerations\n\nSubmitting Genomic Laboratories (SGLs) are expected to have a dedicated high‑throughput network connection (for example, a 10 Gbps upload link).\n\nClients should validate their implementations using **realistically sized datasets and batch sizes** to ensure uploads can reliably complete within the upload session lifetime.\n\n### Worked example: rare disease single-lane upload\n\nThis example walks through a complete upload of a single-lane paired-end FASTQ dataset for a rare disease referral. It shows every HTTP request and response across all six stages.\n\n**Scenario:**\n\n- Referral ID: `r123456789`\n- Participant ID: `p123456789`\n- ODS code: `69A50`\n- Sequencing run ID: `251230_A00123_0001_3F159011F8`\n- Lab sample ID (fluid-x tube number): `123456789`\n- Lane: 1\n- Files:\n  - `sample1_S1_L001_R1_001.fastq.gz` (31,457,280 bytes, SHA-256: `a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5`)\n  - `sample1_S1_L001_R2_001.fastq.gz` (32,505,856 bytes, SHA-256: `b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9`)\n\n### Stage 1: Verify the referral\n\n**Request:**\n\n```shell\nGET /fhir/r4/ServiceRequest?identifier=r123456789&category=https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory|rare-disease-wgs\nAccept: application/fhir+json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n```\n\n**Response (200 OK):**\n\n```json\n{\n\"resourceType\": \"Bundle\",\n\"type\": \"searchset\",\n\"total\": 1,\n\"entry\": [\n    {\n    \"resource\": {\n        \"resourceType\": \"ServiceRequest\",\n        \"id\": \"239218e7-1926-4272-a019-5410baf4c2e0\",\n        \"status\": \"active\",\n        \"intent\": \"order\",\n        \"identifier\": [\n        {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/referral-id\",\n            \"value\": \"r123456789\"\n        }\n        ],\n        \"category\": [\n        {\n            \"coding\": [\n            {\n                \"system\": \"https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory\",\n                \"code\": \"rare-disease-wgs\"\n            }\n            ]\n        }\n        ],\n        \"subject\": {\n        \"type\": \"Patient\",\n        \"identifier\": {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n            \"value\": \"p123456789\"\n        }\n        }\n    }\n    }\n]\n}\n\n```\n\n**What to record:**\n- `service_request_id` = `239218e7-1926-4272-a019-5410baf4c2e0`\n- Participant `p123456789` confirmed in `subject` (proband)\n- No existing `specimen` array on this ServiceRequest (first upload — affects Stage 6 patch format)\n\n### Stage 2: Request upload locations\n\n**Request:**\n\n```bash\nPOST /gel/drsupload/v1/upload-request\nContent-Type: application/json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n```\n\n**Body:**\n\n```json\n{\n\"objects\": [\n    {\n    \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n    \"size\": 31457280,\n    \"mime_type\": \"text/fastq\",\n    \"checksums\": [\n        {\n        \"checksum\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n        \"type\": \"sha-256\"\n        }\n    ]\n    },\n    {\n    \"name\": \"sample1_S1_L001_R2_001.fastq.gz\",\n    \"size\": 32505856,\n    \"mime_type\": \"text/fastq\",\n    \"checksums\": [\n        {\n        \"checksum\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n        \"type\": \"sha-256\"\n        }\n    ]\n    }\n]\n}\n\n```\n\n**Response (200 OK):**\n\n```json\n{\n\"objects\": {\n    \"f47ac10b-58cc-4372-a567-0e02b2c3d479\": {\n    \"id\": \"5918a83b-36e2-4f71-ad1f-b3de3a127314\",\n    \"self_uri\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/5918a83b-36e2-4f71-ad1f-b3de3a127314\",\n    \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n    \"size\": 31457280,\n    \"mime_type\": \"text/fastq\",\n    \"checksums\": [\n        {\n        \"checksum\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n        \"type\": \"sha-256\"\n        }\n    ],\n    \"upload_methods\": [\n        {\n        \"type\": \"s3\",\n        \"access_url\": {\n            \"url\": \"s3://gel-fos-prod-uploads/uploads/5918a83b-36e2-4f71-ad1f-b3de3a127314/sample1_S1_L001_R1_001.fastq.gz\"\n        },\n        \"region\": \"eu-west-2\",\n        \"credentials\": {\n            \"access_key_id\": \"ASIAXXX...\",\n            \"secret_access_key\": \"wJalrXX...\",\n            \"session_token\": \"FwoGZX...\"\n        }\n        }\n    ]\n    },\n    \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\": {\n    \"id\": \"7bf30889-18b6-4e31-bbce-f010f8261b24\",\n    \"self_uri\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/7bf30889-18b6-4e31-bbce-f010f8261b24\",\n    \"name\": \"sample1_S1_L001_R2_001.fastq.gz\",\n    \"size\": 32505856,\n    \"mime_type\": \"text/fastq\",\n    \"checksums\": [\n        {\n        \"checksum\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n        \"type\": \"sha-256\"\n        }\n    ],\n    \"upload_methods\": [\n        {\n        \"type\": \"s3\",\n        \"access_url\": {\n            \"url\": \"s3://gel-fos-prod-uploads/uploads/7bf30889-18b6-4e31-bbce-f010f8261b24/sample1_S1_L001_R2_001.fastq.gz\"\n        },\n        \"region\": \"eu-west-2\",\n        \"credentials\": {\n            \"access_key_id\": \"ASIAXXX...\",\n            \"secret_access_key\": \"wJalrXX...\",\n            \"session_token\": \"FwoGZX...\"\n        }\n        }\n    ]\n    }\n}\n}\n\n```\n\n**Important:** Response objects are keyed by server-generated UUIDs, not by filename. Match response entries back to your files using the `name` field within each object.\n\n**What to record per file:**\n\n- `id` and `self_uri` — needed for Stage 5 DocumentReferences\n- `upload_methods[0].access_url.url` — needed for Stages 3 and 4\n- `upload_methods[0].credentials` — needed for Stage 3\n- `upload_methods[0].region` — needed for Stage 3\n\n### Stage 3: Upload files to S3\n\nFor each file, use the S3 credentials from Stage 2 to upload directly. No API authentication token is needed for this stage.\n\n```python\n\nimport boto3\n\ncreds = upload_method[\"credentials\"]\ns3_client = boto3.client(\n    \"s3\",\n    region_name=upload_method[\"region\"],\n    aws_access_key_id=creds[\"access_key_id\"],\n    aws_secret_access_key=creds[\"secret_access_key\"],\n    aws_session_token=creds[\"session_token\"],\n)\n\n# Parse bucket and key from the access_url, e.g.\n# \"s3://gel-fos-prod-uploads/uploads/.../sample1_S1_L001_R1_001.fastq.gz\"\nbucket = \"gel-fos-prod-uploads\"\nkey = \"uploads/5918a83b-.../sample1_S1_L001_R1_001.fastq.gz\"\n\ns3_client.upload_file(\n    Filename=\"/path/to/sample1_S1_L001_R1_001.fastq.gz\",\n    Bucket=bucket,\n    Key=key,\n)\n\n```\n\nRepeat for each file.\n\n### Stage 4: Register DRS objects\n\nThis example registers the two files in a single request. In practice, registration requests are limited to 20 candidate objects and larger upload batches must be split across multiple Stage 4 calls.\n\n**Request:**\n\n```bash\n\nPOST /gel/drsupload/v1/register-objects\nContent-Type: application/json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n\n```\n\n**Body:**\n\n```json\n\n{\n\"candidates\": [\n    {\n    \"name\": \"sample1_S1_L001_R1_001.fastq.gz\",\n    \"size\": 31457280,\n    \"mime_type\": \"text/fastq\",\n    \"checksums\": [\n        {\n        \"checksum\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n        \"type\": \"sha-256\"\n        }\n    ],\n    \"access_methods\": [\n        {\n        \"type\": \"s3\",\n        \"access_url\": {\n            \"url\": \"s3://gel-fos-prod-uploads/uploads/5918a83b-36e2-4f71-ad1f-b3de3a127314/sample1_S1_L001_R1_001.fastq.gz\"\n        }\n        }\n    ]\n    },\n    {\n    \"name\": \"sample1_S1_L001_R2_001.fastq.gz\",\n    \"size\": 32505856,\n    \"mime_type\": \"text/fastq\",\n    \"checksums\": [\n        {\n        \"checksum\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n        \"type\": \"sha-256\"\n        }\n    ],\n    \"access_methods\": [\n        {\n        \"type\": \"s3\",\n        \"access_url\": {\n            \"url\": \"s3://gel-fos-prod-uploads/uploads/7bf30889-18b6-4e31-bbce-f010f8261b24/sample1_S1_L001_R2_001.fastq.gz\"\n        }\n        }\n    ]\n    }\n]\n}\n\n```\n\n**Response: 201 Created**\n\n### Stage 5: Submit the FHIR transaction Bundle\n\nThe transaction Bundle references the ServiceRequest ID from Stage 1 and the DRS URIs from Stage 4. Note that intra-Bundle references use `urn:uuid:` format; references to existing resources (the ServiceRequest) use `ResourceType/{id}` format.\n\n**Important**\n\nThe DocumentReference resources in this transaction Bundle reference the DRS object URIs returned from **Stage 4 (register-objects)**.\n\nAlthough Stage 2 also returns object identifiers and DRS URIs, those are **temporary and must not be used** in FHIR DocumentReference resources.\n\n**Request:**\n\n```bash\n\nPOST /fhir/r4\nContent-Type: application/fhir+json\nAccept: application/fhir+json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n\n```\n\n**Body:**\n\n<details>\n<summary>Click to see an example FHIR transaction Bundle</summary>\n\n```json\n{\n\"resourceType\": \"Bundle\",\n\"type\": \"transaction\",\n\"entry\": [\n    {\n    \"fullUrl\": \"urn:uuid:c1d2e3f4-a5b6-7890-cdef-1234567890ab\",\n    \"resource\": {\n        \"resourceType\": \"Specimen\",\n        \"status\": \"available\",\n        \"extension\": [\n        {\n            \"url\": \"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory\",\n            \"valueCodeableConcept\": {\n            \"coding\": [\n                {\n                \"system\": \"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory\",\n                \"code\": \"germline\"\n                }\n            ]\n            }\n        },\n        {\n            \"url\": \"https://genomicsengland.co.uk/fhir/StructureDefinition/gel1001-primary-sample-state\",\n            \"valueCodeableConcept\": {\n            \"coding\": [\n                {\n                \"system\": \"https://genomicsengland.co.uk/fhir/CodeSystem/gel1001-primary-sample-state\",\n                \"code\": \"blood_unsorted_edta\"\n                }\n            ]\n            }\n        }\n        ],\n        \"type\": {\n        \"coding\": [\n            {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/data-specimen-type\",\n            \"code\": \"wgs-data\"\n            }\n        ]\n        },\n        \"subject\": {\n        \"type\": \"Patient\",\n        \"identifier\": {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n            \"value\": \"p123456789\"\n        }\n        },\n        \"request\": [\n        { \"reference\": \"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\" }\n        ],\n        \"parent\": [\n        { \"reference\": \"urn:uuid:d2e3f4a5-b6c7-8901-def0-234567890abc\" }\n        ]\n    },\n    \"request\": { \"method\": \"POST\", \"url\": \"Specimen\" }\n    },\n    {\n    \"fullUrl\": \"urn:uuid:d2e3f4a5-b6c7-8901-def0-234567890abc\",\n    \"resource\": {\n        \"resourceType\": \"Specimen\",\n        \"status\": \"available\",\n        \"extension\": [\n        {\n            \"url\": \"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory\",\n            \"valueCodeableConcept\": {\n            \"coding\": [\n                {\n                \"system\": \"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory\",\n                \"code\": \"germline\"\n                }\n            ]\n            }\n        }\n        ],\n        \"identifier\": [\n        {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/lab-sample-id\",\n            \"value\": \"123456789\",\n            \"assigner\": {\n            \"type\": \"Organization\",\n            \"identifier\": {\n                \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n                \"value\": \"69A50\"\n            }\n            }\n        }\n        ],\n        \"subject\": {\n        \"type\": \"Patient\",\n        \"identifier\": {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n            \"value\": \"p123456789\"\n        }\n        }\n    },\n    \"request\": { \"method\": \"POST\", \"url\": \"Specimen\" }\n    },\n    {\n    \"fullUrl\": \"urn:uuid:e3f4a5b6-c7d8-9012-ef01-34567890abcd\",\n    \"resource\": {\n        \"resourceType\": \"Procedure\",\n        \"identifier\": [\n        {\n            \"system\": \"https://69A50.nhs.uk/sequencing-run-id\",\n            \"value\": \"251230_A00123_0001_3F159011F8\"\n        }\n        ],\n        \"basedOn\": [\n        {\n            \"type\": \"ServiceRequest\",\n            \"identifier\": {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/referral-id\",\n            \"value\": \"r123456789\"\n            }\n        }\n        ],\n        \"status\": \"completed\",\n        \"code\": {\n        \"coding\": [\n            {\n            \"system\": \"http://snomed.info/sct\",\n            \"code\": \"51201000000109\",\n            \"display\": \"Whole genome sequencing\"\n            }\n        ]\n        },\n        \"subject\": {\n        \"type\": \"Patient\",\n        \"identifier\": {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n            \"value\": \"p123456789\"\n        }\n        },\n        \"performer\": [\n        {\n            \"actor\": {\n            \"type\": \"Organization\",\n            \"identifier\": {\n                \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n                \"value\": \"69A50\"\n            }\n            }\n        }\n        ]\n    },\n    \"request\": { \"method\": \"POST\", \"url\": \"Procedure\" }\n    },\n    {\n    \"fullUrl\": \"urn:uuid:f4a5b6c7-d8e9-0123-f012-4567890abcde\",\n    \"resource\": {\n        \"resourceType\": \"DocumentReference\",\n        \"extension\": [{ \"url\": \"lane_number\", \"valuePositiveInt\": 1 }],\n        \"identifier\": [\n        {\n            \"system\": \"https://69A50.nhs.uk/file-id\",\n            \"value\": \"sample1_S1_L001_R1_001.fastq.gz\"\n        }\n        ],\n        \"status\": \"current\",\n        \"docStatus\": \"final\",\n        \"subject\": {\n        \"type\": \"Patient\",\n        \"identifier\": {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n            \"value\": \"p123456789\"\n        }\n        },\n        \"author\": [\n        {\n            \"type\": \"Organization\",\n            \"identifier\": {\n            \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n            \"value\": \"69A50\"\n            }\n        }\n        ],\n        \"relatesTo\": [\n        {\n            \"code\": \"appends\",\n            \"target\": { \"reference\": \"urn:uuid:a5b6c7d8-e9f0-1234-0123-567890abcdef\" }\n        }\n        ],\n        \"content\": [\n        {\n            \"attachment\": {\n            \"contentType\": \"text/fastq\",\n            \"url\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/5918a83b-36e2-4f71-ad1f-b3de3a127314\",\n            \"hash\": \"a3f1b7c9d2e4f6a8b0c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5\",\n            \"size\": 31457280,\n            \"title\": \"sample1_S1_L001_R1_001.fastq.gz\"\n            }\n        }\n        ],\n        \"context\": {\n        \"related\": [\n            { \"reference\": \"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\" },\n            { \"reference\": \"urn:uuid:c1d2e3f4-a5b6-7890-cdef-1234567890ab\", \"type\": \"Specimen\" },\n            { \"reference\": \"urn:uuid:e3f4a5b6-c7d8-9012-ef01-34567890abcd\", \"type\": \"Procedure\" }\n        ]\n        }\n    },\n    \"request\": { \"method\": \"POST\", \"url\": \"DocumentReference\" }\n    },\n    {\n    \"fullUrl\": \"urn:uuid:a5b6c7d8-e9f0-1234-0123-567890abcdef\",\n    \"resource\": {\n        \"resourceType\": \"DocumentReference\",\n        \"extension\": [{ \"url\": \"lane_number\", \"valuePositiveInt\": 1 }],\n        \"identifier\": [\n        {\n            \"system\": \"https://69A50.nhs.uk/file-id\",\n            \"value\": \"sample1_S1_L001_R2_001.fastq.gz\"\n        }\n        ],\n        \"status\": \"current\",\n        \"docStatus\": \"final\",\n        \"subject\": {\n        \"type\": \"Patient\",\n        \"identifier\": {\n            \"system\": \"https://genomicsengland.co.uk/healthcare/participant-id\",\n            \"value\": \"p123456789\"\n        }\n        },\n        \"author\": [\n        {\n            \"type\": \"Organization\",\n            \"identifier\": {\n            \"system\": \"https://fhir.nhs.uk/Id/ods-organization-code\",\n            \"value\": \"69A50\"\n            }\n        }\n        ],\n        \"relatesTo\": [\n        {\n            \"code\": \"transforms\",\n            \"target\": { \"reference\": \"urn:uuid:f4a5b6c7-d8e9-0123-f012-4567890abcde\" }\n        }\n        ],\n        \"content\": [\n        {\n            \"attachment\": {\n            \"contentType\": \"text/fastq\",\n            \"url\": \"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/7bf30889-18b6-4e31-bbce-f010f8261b24\",\n            \"hash\": \"b4e2c8d3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9\",\n            \"size\": 32505856,\n            \"title\": \"sample1_S1_L001_R2_001.fastq.gz\"\n            }\n        }\n        ],\n        \"context\": {\n        \"related\": [\n            { \"reference\": \"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\" },\n            { \"reference\": \"urn:uuid:c1d2e3f4-a5b6-7890-cdef-1234567890ab\", \"type\": \"Specimen\" },\n            { \"reference\": \"urn:uuid:e3f4a5b6-c7d8-9012-ef01-34567890abcd\", \"type\": \"Procedure\" }\n        ]\n        }\n    },\n    \"request\": { \"method\": \"POST\", \"url\": \"DocumentReference\" }\n    }\n]\n}\n\n```\n\n</details>\n\n**Response (200 OK):**\n\n```json\n{\n\"resourceType\": \"Bundle\",\n\"type\": \"transaction-response\",\n\"entry\": [\n    { \"response\": { \"status\": \"201 Created\", \"location\": \"Specimen/aabbccdd-1122-3344-5566-778899aabbcc/_history/1\" } },\n    { \"response\": { \"status\": \"201 Created\", \"location\": \"Specimen/eeff0011-2233-4455-6677-8899aabbccdd/_history/1\" } },\n    { \"response\": { \"status\": \"201 Created\", \"location\": \"Procedure/11223344-5566-7788-99aa-bbccddeeff00/_history/1\" } },\n    { \"response\": { \"status\": \"201 Created\", \"location\": \"DocumentReference/22334455-6677-8899-aabb-ccddeeff0011/_history/1\" } },\n    { \"response\": { \"status\": \"201 Created\", \"location\": \"DocumentReference/33445566-7788-99aa-bbcc-ddeeff001122/_history/1\" } }\n]\n}\n\n```\n\n**What to record:** The first Specimen entry is the wgs-data child. Extract its ID: `aabbccdd-1122-3344-5566-778899aabbcc`.\n\n### Stage 6: Patch the ServiceRequest\n\nThis ServiceRequest had no existing `specimen` array (as observed in Stage 1), so the first operation uses `\"path\": \"/specimen\"` to create it.\n\n**Request:**\n\n```bash\n\nPATCH /fhir/r4/ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0\nContent-Type: application/json-patch+json\nAccept: application/fhir+json\nAuthorization: Bearer {access_token}\n# or \napikey: {api_key}\n\n```\n\n**Body:**\n\n```json\n[\n{\n    \"op\": \"add\",\n    \"path\": \"/specimen\",\n    \"value\": [\n    { \"reference\": \"Specimen/aabbccdd-1122-3344-5566-778899aabbcc\" }\n    ]\n}\n]\n\n```\n\n**Response (200 OK):** Returns the updated ServiceRequest with the new `specimen` array.\n\nThe upload is now complete. The wgs-data Specimen reference on the ServiceRequest triggers downstream processing by the GEL WGS bioinformatics pipelines.\n\n### Multi-lane uploads\n\nFor samples sequenced across multiple lanes, the transaction Bundle structure is the same except:\n\n- Add one additional DocumentReference pair (Read 1 + Read 2) per extra lane\n- All DocumentReferences share the same Specimen and Procedure resources\n- Each DocumentReference pair has its own `lane_number` extension value\n\n## Who can use this API\n\nThis API can only be used by staff associated with Genomic Laboratory Hubs (GLHs) operating as part of the Genomic Medicine Service (GMS) where there is a legal basis to do so.\n\n## Access modes\n\nAccess to endpoints is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) and uses the NHS API Platform's 'signed JSON Web Token (JWT) authentication' method.\n\nTo set this up, see [NHS API Platform instructions](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication).\n\n## Status and roadmap\n\nIn development\n\n## Service level\n\nThis API is a silver service, meaning it is operational and supported 24 hours a day, 365 days a year.\n\nFor more information, [see service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Rate limits\n\nThe default rate limit is 5TPS (transactions per second) per app. If you require a higher rate limit please contact us or raise this during the onboarding process.\n\n[Contact Genomics England support desk](https://www.genomicsengland.co.uk/service-desk)\n\n## Technology\n\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).\n\nIt conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) and [GA4GH](https://www.ga4gh.org/) global standards.\n\nRefer to [Genomics FHIR Implementation Guide](https://simplifier.net/guide/fhir-genomics-implementation-guide/Home?version=current) for more details about implementation requirements.\n\nThis specification is based on UK Core Ballot2 and conforms to the same.\n\n## Network access\n\nThis API is available on the internet. For more details [see Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Errors\n\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n- 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n- 400 to 499 if it failed because of a client error by your application\n- 500 to 599 if it failed because of an error on our server\n\nErrors specific to this API are shown in the Operations section, under Response.\n\n[See the reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\n## Open source\n\nThe following [open source resources](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) may be useful.\n\n## Environments and testing\n\n| Environment      | Base URL                                                 |\n| ---------------- | -------------------------------------------------------- |\n| Dev              | `https://dep.api.service.nhs.uk/upload-genomic-data-dep` |\n| Integration test | `https://int.api.service.nhs.uk/upload-genomic-data`     |\n| Production       | `https://api.service.nhs.uk/upload-genomic-data`         |\n\n## Onboarding\n\nThis API is in the Alpha stage of development.\n\nYou cannot use the digital onboarding service (DOS) until it moves into Beta stage.\n\nOnce this happens, you will need to get your software approved by Genomics England. This takes about 5 working days.\n\nTo understand how the NHS API Platform digital onboarding process works, [see digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding).\n","contact":{"name":"Genomics England","url":"https://www.genomicsengland.co.uk/","email":"ge-servicedesk@genomicsengland.co.uk"},"license":{"name":"TBC","url":"TBC"},"version":"v1.0"},"servers":[{"url":"https://dep.api.service.nhs.uk/upload-genomic-data-dep","description":"NHS APIM development/deployment"},{"url":"https://int.api.service.nhs.uk/upload-genomic-data","description":"NHS APIM integration"},{"url":"https://api.service.nhs.uk/upload-genomic-data","description":"NHS APIM production"}],"paths":{"/ga4gh/drs/v1/objects/{object_id}":{"get":{"tags":["GA4GH DRS endpoints"],"summary":"Get info about a DrsObject.","operationId":"GetDrsObject","parameters":[{"name":"object_id","in":"path","description":"DrsObject identifier","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The DrsObject was found successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsObjectResponse"}}}},"202":{"description":"The operation is delayed and will continue asynchronously. The client should retry this same request after the delay specified by Retry-After header.","headers":{"Retry-After":{"name":"","in":"header","description":"Delay in seconds. The client should retry this same request after waiting for this duration. To simplify client response processing, this must be an integral relative time in seconds. This value SHOULD represent the minimum duration the client should wait before attempting the operation again with a reasonable expectation of success. When it is not feasible for the server to determine the actual expected delay, the server may return a brief, fixed value instead.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"integer"}}}},"400":{"description":"The request is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"403":{"description":"The requester is not authorized to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"404":{"description":"The requested DrsObject wasn't found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}}},"deprecated":false}},"/gel/drsupload/v1/register-objects":{"post":{"tags":["GA4GH DRS endpoints"],"summary":"Register candidates as new DRS Objects.","operationId":"registerDrsObjects","requestBody":{"description":"An array of DRS Objects to register.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterDrsObjectsRequest"}}},"required":true},"responses":{"201":{"description":"DRS Objects registered successfully"},"400":{"description":"At least one candidate DRS Object is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"403":{"description":"The requester is not authorized to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"409":{"description":"Duplicate candidate DRS Object names detected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}}},"deprecated":false}},"/gel/drsupload/v1/upload-request":{"post":{"tags":["GA4GH DRS endpoints"],"summary":"Request upload locations and credentials for files","operationId":"requestDrsUpload","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsUploadRequest"}}},"required":true},"responses":{"200":{"description":"Upload locations and credentials created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsUploadResponse"}}}},"400":{"description":"Malformed DRS upload request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"403":{"description":"The requester is not authorized to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrsErrorResponse"}}}}},"deprecated":false}},"/fhir/r4/ServiceRequest":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for ServiceRequest resource type","description":"Performs a standard FHIR search against the ServiceRequest resource.  Returns a Bundle\nof type `searchset` containing ServiceRequest resources  that match the supplied \nsearch parameters.\n","parameters":[{"name":"identifier","in":"query","description":"NGIS referral ID","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"r123456789"},{"name":"category","in":"query","description":"The category of the ServiceRequest (e.g. rare-disease-wgs or cancer-wgs)\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory|rare-disease-wgs"},{"name":"subject:identifier","in":"query","description":"Identifier of the ServiceRequest subject i.e. proband, expressed as a chained search  on \nServiceRequest.subject. Typically an NGIS proband identifier.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"p123456789"},{"name":"requester:identifier","in":"query","description":"Identifier of the ServiceRequest requester, expressed as a chained search  on \nServiceRequest.requester. Typically an ODS organisation code.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"699P0"},{"name":"performer:identifier","in":"query","description":"Identifier of the ServiceRequest performer, expressed as a chained search  on \nServiceRequest.performer. Typically an ODS organisation code.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"699P0"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/ServiceRequest/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Look up a specific ServiceRequest","parameters":[{"name":"id","in":"path","description":"The FHIR ServiceRequest \"id\"","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"1914486a-3302-4664-b4e4-b79140020059"}],"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirServiceRequest"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"deprecated":false},"patch":{"tags":["HL7 FHIR endpoints"],"summary":"Update ServiceRequest","description":"Updates a ServiceRequest using JSON Patch (RFC 6902). In the upload protocol, this is used in Stage 6 to add wgs-data Specimen references to `ServiceRequest.specimen`, which triggers downstream bioinformatics pipelines.\n\nThe request body must use Content-Type `application/json-patch+json`.\n","parameters":[{"name":"id","in":"path","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/JsonPatchDocument"}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirServiceRequest"}}}},"201":{"description":"Created","headers":{"Location":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"}}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirServiceRequest"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Specimen":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for Specimen resource type","description":"Performs a standard FHIR search against the Specimen resource.  Returns a Bundle\nof type `searchset` containing Specimen resources that match the supplied \nsearch parameters.\n","parameters":[{"name":"identifier","in":"query","description":"Specimen identifier (e.g. depending on the Specimen \"type\" either  fluid-x tube number (lab-sample-id) or GEL sample ID. Format: {system}|{value} e.g. https://genomicsengland.co.uk/healthcare/lab-sample-id|123456789\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/sample-id|s_01km2v4qrfez18h0517d2db4ef"},{"name":"subject:identifier","in":"query","description":"Patient / participant identifier associated with the Specimen.\nFormat: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/participant-id|p123456789"},{"name":"type","in":"query","description":"Specimen type code (e.g. wgs-data).\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"wgs-data"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Specimen/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Get a Specimen by ID","description":"Retrieve a single Specimen resource by its logical id.","operationId":"getSpecimenById","parameters":[{"name":"id","in":"path","description":"Logical id of the Specimen resource","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"002634d2-5d6b-4fcb-af24-dc0690a72a90"}],"responses":{"200":{"description":"Specimen resource","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirSpecimen"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/DocumentReference":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for DocumentReference resource type","description":"Performs a standard FHIR search against the DocumentReference resource.  Returns a Bundle\nof type `searchset` containing DocumentReference resources that match the supplied \nsearch parameters.\n","parameters":[{"name":"subject","in":"query","description":"Reference to the Patient","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"Patient/5db37923-d212-42f7-aaaf-9035f301e26f"},{"name":"identifier","in":"query","description":"DocumentReference identifier e.g. the file name Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://ods123.nhs.uk/file-id|myfile.fastq.gz"},{"name":"subject:identifier","in":"query","description":"Patient / participant identifier associated with the DocumentReference.\nFormat: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/participant-id|p123456789"},{"name":"status","in":"query","description":"DocumentReference status","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"enum":["current","superseded","entered-in-error"],"type":"string"},"example":"current"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/DocumentReference/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Look up a specific DocumentReference","parameters":[{"name":"id","in":"path","description":"The FHIR DocumentReference \"id\"","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"00044410-e9e6-4bfc-890c-436a4c06a05e"}],"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirDocumentReference"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Procedure":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Search for Procedure resource type","description":"Performs a standard FHIR search against the Procedure resource.  Returns a Bundle\nof type `searchset` containing Procedure resources that match the supplied \nsearch parameters.\n","parameters":[{"name":"subject","in":"query","description":"Reference to the Patient","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"Patient/50102606-7edb-4385-a01c-8d689d2702b2"},{"name":"subject:identifier","in":"query","description":"Patient participant NGIS identifier. Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/participant-id|p123456789"},{"name":"identifier","in":"query","description":"Sequencing run identifier. Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://ods123.nhs.uk/sequencing-run-id|251230_A00123_0001_3F159011F8"},{"name":"based-on:identifier","in":"query","description":"Referral identifier from the originating ServiceRequest Format: {system}|{value}\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"https://genomicsengland.co.uk/healthcare/referral-id|r123456789"}],"responses":{"200":{"description":"Success - Returns a Bundle","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4/Procedure/{id}":{"get":{"tags":["HL7 FHIR endpoints"],"summary":"Look up a specific Procedure","parameters":[{"name":"id","in":"path","description":"The FHIR Procedure \"id\"","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"2565ab5e-b110-4252-b1ee-e58ed0b1f070"}],"responses":{"200":{"description":"Success","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirProcedure"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}},"/fhir/r4":{"post":{"tags":["HL7 FHIR endpoints"],"summary":"Submit a FHIR R4 transaction Bundle","description":"Submits a FHIR R4 transaction Bundle. The server processes each entry and returns a transaction-response Bundle. The request Bundle must have `type` set to `transaction`.\n","requestBody":{"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}},"required":true},"responses":{"200":{"description":"Success - Bundle processed (OK)","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"201":{"description":"Success - Bundle processed and resources created","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/ServerError"}},"deprecated":false}}},"components":{"schemas":{"FhirServiceRequest":{"type":"object","description":"A FHIR R4 ServiceRequest resource. See the [FHIR R4 ServiceRequest documentation](https://hl7.org/fhir/R4/servicerequest.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/servicerequest.html"},"example":{"resourceType":"ServiceRequest","id":"239218e7-1926-4272-a019-5410baf4c2e0","meta":{"versionId":"1","lastUpdated":"2026-03-27T20:46:10.783652042Z"},"identifier":[{"system":"https://genomicsengland.co.uk/healthcare/referral-id","value":"r123456789"}],"status":"active","intent":"order","category":[{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-GenomeSequencingCategory","code":"rare-disease-wgs"}]}],"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p123456789"}}}},"FhirSpecimen":{"type":"object","description":"A FHIR R4 Specimen resource. See the [FHIR R4 Specimen documentation](https://hl7.org/fhir/R4/specimen.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/specimen.html"},"example":{"resourceType":"Specimen","id":"002634d2-5d6b-4fcb-af24-dc0690a72a90","meta":{"versionId":"1","lastUpdated":"2026-03-19T10:44:29.324070944Z"},"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory","code":"germline"}]}},{"url":"https://genomicsengland.co.uk/fhir/StructureDefinition/gel1001-primary-sample-state","valueCodeableConcept":{"coding":[{"system":"https://genomicsengland.co.uk/fhir/CodeSystem/gel1001-primary-sample-state","code":"blood_unsorted_edta"}]}}],"type":{"coding":[{"system":"https://genomicsengland.co.uk/healthcare/data-specimen-type","code":"wgs-data"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p73353612603"}},"request":[{"reference":"ServiceRequest/239218e7-1926-4272-a019-5410baf4c2e0"}],"parent":[{"reference":"Specimen/2db7b176-fbf1-432b-8cb2-0fa51d502cdd"}],"identifier":[{"system":"https://genomicsengland.co.uk/healthcare/sample-id","value":"s_01km2v4qrfez18h0517d2db4ef"}]}},"FhirProcedure":{"type":"object","description":"A FHIR R4 Procedure resource. See the [FHIR R4 Procedure documentation](https://hl7.org/fhir/R4/procedure.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/procedure.html"},"example":{"resourceType":"Procedure","id":"2565ab5e-b110-4252-b1ee-e58ed0b1f070","identifier":[{"system":"https://69A50.nhs.uk/sequencing-run-id","value":"251230_A00123_0001_3F159011F8"}],"basedOn":[{"type":"ServiceRequest","identifier":{"system":"https://genomicsengland.co.uk/healthcare/referral-id","value":"r123456789"}}],"status":"completed","code":{"coding":[{"system":"http://snomed.info/sct","code":51201000000109,"display":"Whole genome sequencing"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p123456789"}},"performer":[{"actor":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"69A50"}}}],"meta":{"versionId":"1","lastUpdated":"2026-03-24T20:33:24.908401588Z"}}},"FhirDocumentReference":{"type":"object","description":"A FHIR R4 DocumentReference resource. See the [FHIR R4 DocumentReference documentation](https://hl7.org/fhir/R4/documentreference.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/documentreference.html"},"example":{"resourceType":"DocumentReference","id":"00044410-e9e6-4bfc-890c-436a4c06a05e","meta":{"versionId":"1","lastUpdated":"2026-03-13T18:12:57.157802680Z"},"extension":[{"url":"lane_number","valuePositiveInt":5}],"identifier":[{"system":"https://ods123.nhs.uk/file-id","value":"my-fastq.fastq.gz"}],"status":"current","docStatus":"final","subject":{"reference":"Patient/5db37923-d212-42f7-aaaf-9035f301e26f","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"p123456789"}},"author":[{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"69A50"}}],"relatesTo":[{"code":"appends","target":{"reference":"DocumentReference/956f244a-766f-451a-acaa-99cda79be373"}}],"content":[{"attachment":{"contentType":"text/fastq","url":"drs://api.service.nhs.uk/upload-genomic-data/ga4gh/drs/v1/objects/5918a83b-36e2-4f71-ad1f-b3de3a127314","hash":"ca1cf98c789b28c46af29493b5375ae3986a60a1cf8c78a849d8d36c40ab82ed","title":"my-fastq.fastq.gz"}}],"context":{"related":[{"reference":"ServiceRequest/10bbd33e-0676-4f95-ba41-dc9850956889"},{"reference":"Specimen/0d19b909-e6ba-4d95-9dde-b64c7f417fde","type":"Specimen"},{"reference":"Procedure/f6b8c147-c4ae-4c63-8cb6-5098766c64c4","type":"Procedure"}]}}},"FhirBundle":{"type":"object","description":"A FHIR R4 Bundle resource used as a transaction container. See the [FHIR R4 Bundle documentation](https://hl7.org/fhir/R4/bundle.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/bundle.html"},"example":{"resourceType":"Bundle","type":"transaction","entry":[{"fullUrl":"urn:uuid:{specimen_child_random_uuid}","resource":{"resourceType":"Specimen","status":"available","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory","code":"{sample_category}"}]}},{"url":"https://genomicsengland.co.uk/fhir/StructureDefinition/gel1001-primary-sample-state","valueCodeableConcept":{"coding":[{"system":"https://genomicsengland.co.uk/fhir/CodeSystem/gel1001-primary-sample-state","code":"{gel1001_sample_state}"}]}}],"type":{"coding":[{"system":"https://genomicsengland.co.uk/healthcare/data-specimen-type","code":"wgs-data"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"request":[{"reference":"ServiceRequest/{service_request_id}"}],"parent":[{"reference":"urn:uuid:{specimen_parent_random_uuid}"}]},"request":{"method":"POST","url":"Specimen"}},{"fullUrl":"urn:uuid:{specimen_parent_random_uuid}","resource":{"resourceType":"Specimen","status":"available","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-SampleCategory","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-SampleCategory","code":"{sample_category}"}]}}],"identifier":[{"system":"https://genomicsengland.co.uk/healthcare/lab-sample-id","value":"{random_lsid}","assigner":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}}],"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}}},"request":{"method":"POST","url":"Specimen"}},{"fullUrl":"urn:uuid:{procedure_random_uuid}","resource":{"resourceType":"Procedure","identifier":[{"system":"https://\"{ods_code}\".nhs.uk/sequencing-run-id","value":"{sequencing_run_id}"}],"basedOn":[{"type":"ServiceRequest","identifier":{"system":"https://genomicsengland.co.uk/healthcare/referral-id","value":"{referral_id}"}}],"status":"completed","code":{"coding":[{"system":"http://snomed.info/sct","code":"51201000000109","display":"Whole genome sequencing"}]},"subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"performer":[{"actor":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}}]},"request":{"method":"POST","url":"Procedure"}},{"fullUrl":"urn:uuid:{read1_ref_uuid}","resource":{"resourceType":"DocumentReference","extension":[{"url":"lane_number","valuePositiveInt":"{lane_id}"}],"identifier":[{"system":"https://\"{ods_code}\".nhs.uk/file-id","value":"{read1_filename}"}],"status":"current","docStatus":"final","subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"author":[{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}],"relatesTo":[{"code":"appends","target":{"reference":"urn:uuid:{read2_ref_uuid}"}}],"content":[{"attachment":{"contentType":"text/fastq","url":"{read1_drs_uri}","hash":"{read1_checksum}","title":"{read1_filename}"}}],"context":{"related":[{"reference":"ServiceRequest/{service_request_id}"},{"reference":"urn:uuid:{specimen_child_random_uuid}","type":"Specimen"},{"reference":"urn:uuid:{procedure_random_uuid}","type":"Procedure"}]}},"request":{"method":"POST","url":"DocumentReference"}},{"fullUrl":"urn:uuid:{read2_ref_uuid}","resource":{"resourceType":"DocumentReference","extension":[{"url":"lane_number","valuePositiveInt":"{lane_id}"}],"identifier":[{"system":"https://\"{ods_code}\".nhs.uk/file-id","value":"{read2_filename}"}],"status":"current","docStatus":"final","subject":{"type":"Patient","identifier":{"system":"https://genomicsengland.co.uk/healthcare/participant-id","value":"{participant_id}"}},"author":[{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"{ods_code}"}}],"relatesTo":[{"code":"transforms","target":{"reference":"urn:uuid:{read1_ref_uuid}"}}],"content":[{"attachment":{"contentType":"text/fastq","url":"{read2_drs_uri}","hash":"{read2_checksum}","title":"{read2_filename}"}}],"context":{"related":[{"reference":"ServiceRequest/{service_request_id}"},{"reference":"urn:uuid:{specimen_child_random_uuid}","type":"Specimen"},{"reference":"urn:uuid:{procedure_random_uuid}","type":"Procedure"}]}},"request":{"method":"POST","url":"DocumentReference"}}]}},"FhirOperationOutcome":{"type":"object","description":"A FHIR R4 OperationOutcome resource returned when an error occurs. See the [FHIR R4 OperationOutcome documentation](https://hl7.org/fhir/R4/operationoutcome.html) for the full schema and field definitions.\n","externalDocs":{"url":"https://hl7.org/fhir/R4/operationoutcome.html"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"invalid","details":{"text":"ServiceRequest/service-request-001 not found"},"diagnostics":"The referenced ServiceRequest does not exist or you do not have permission to access it"}]}},"JsonPatchDocument":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/JsonPatchOperation"},"description":"JSON Patch (RFC 6902) document used with the FHIR PATCH interaction. Use with Content-Type: application/json-patch+json. [1](https://swagger.io/docs/specification/v3_0/adding-examples/)[2](https://github.com/microsoft/fhir-server/blob/main/docs/rest/JsonPatchRequests.http)\n","example":[{"op":"replace","path":"/status","value":"completed"},{"op":"add","path":"/specimen/-","value":{"reference":"Specimen/7bf30889-18b6-4e31-bbce-f010f8261b24"}}]},"Checksum":{"required":["checksum","type"],"type":"object","properties":{"checksum":{"type":"string","description":"The hex-string encoded checksum for the data."},"type":{"type":"string","description":"The digest method used to create the checksum. The value (e.g. sha-256) SHOULD be listed as Hash Name String in the https://www.iana.org/assignments/named-information/named-information.xhtml#hash-alg[IANA\n"}}},"AccessUrl":{"required":["url"],"type":"object","properties":{"url":{"type":"string","description":"A fully resolvable URL that can be used to fetch the actual object bytes."},"headers":{"type":"array","items":{"type":"string"},"description":"An optional list of headers to include in the HTTP request to url. These headers can be used to provide auth tokens required to fetch the object bytes.\n"}}},"AccessMethod":{"required":["type"],"type":"object","properties":{"type":{"enum":["s3","gs","ftp","gsiftp","globus"],"type":"string","description":"Type of the access method."},"access_url":{"$ref":"#/components/schemas/AccessUrl"},"access_id":{"type":"string","description":"An arbitrary string to be passed to the /access method to get an AccessURL. This string must be unique within the scope of a single object. Note that at least one of access_url and access_id must be provided.\n"},"region":{"type":"string","description":"The region where the object is stored."}}},"ContentsObject":{"required":["name"],"type":"object","properties":{"name":{"type":"string","description":"A name declared by the bundle author that must be used when materialising this object, overriding any name directly associated with the object itself. The name must be unique with the containing bundle. This string is made up of uppercase and lowercase letters, decimal digits, hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].\n"},"id":{"type":"string","description":"A DRS identifier of a DrsObject (either a single blob or a nested bundle). If this ContentsObject is an object within a nested bundle, then the id is optional. Otherwise, the id is required.\n"},"drs_uri":{"type":"string","description":"A list of full DRS identifier URI paths that may be used to obtain the object. These URIs may be external to this DRS instance.\n"},"contents":{"type":"array","items":{"$ref":"#/components/schemas/ContentsObject"},"description":"If this ContentsObject describes a nested bundle and the caller specified \"?expand=true\" on the request, then this contents array must be present and describe the objects within the nested bundle.\n"}}},"DrsObjectResponse":{"required":["id","self_uri","size","created_time","checksums"],"type":"object","properties":{"id":{"type":"string","description":"An identifier unique to this DrsObject."},"name":{"pattern":"^[A-Za-z0-9.\\-_~]+$","type":"string","description":"A string that can be used to name a DrsObject. This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_].\n"},"self_uri":{"type":"string","description":"A drs:// hostname-based URI, as defined in the DRS documentation, that tells clients how to access this object.\n"},"size":{"type":"integer","description":"For blobs, the blob size in bytes. For bundles, the cumulative size, in bytes, of items in the contents field.\n","format":"int64"},"created_time":{"type":"string","description":"Timestamp of content creation in RFC3339. (This is the creation time of the underlying content, not of the JSON object.)\n","format":"date-time"},"updated_time":{"type":"string","description":"Timestamp of content update in RFC3339, identical to created_time in systems that do not support updates. (This is the update time of the underlying content, not of the JSON object.)\n","format":"date-time"},"version":{"type":"string","description":"A string representing a version."},"mime_type":{"type":"string","description":"A string providing the mime-type of the DrsObject."},"checksums":{"type":"array","items":{"$ref":"#/components/schemas/Checksum"},"description":"The checksum of the DrsObject. At least one checksum must be provided. For blobs, the checksum is computed over the bytes in the blob. For bundles, the checksum is computed over a sorted concatenation of the checksums of its top-level contained objects (not recursive, names not included). The list of checksums is sorted alphabetically (hex-code) before concatenation and a further checksum is performed on the concatenated checksum value. For example, if a bundle contains blobs with the following checksums: md5(blob1) = 72794b6d md5(blob2) = 5e089d29 Then the checksum of the bundle is: md5( concat( sort( md5(blob1), md5(blob2) ) ) ) = md5( concat( sort( 72794b6d, 5e089d29 ) ) ) = md5( concat( 5e089d29, 72794b6d ) ) = md5( 5e089d2972794b6d ) = f7a29a04\n"},"access_methods":{"type":"array","items":{"$ref":"#/components/schemas/AccessMethod"},"description":"The list of access methods that can be used to fetch the DrsObject. Required for single blobs; optional for bundles.\n"},"contents":{"type":"array","items":{"$ref":"#/components/schemas/ContentsObject"},"description":"If not set, this DrsObject is a single blob. If set, this DrsObject is a bundle containing the listed ContentsObjects (some of which may be further nested).\n"},"description":{"type":"string","description":"A human readable description of the DrsObject."},"aliases":{"type":"array","items":{"type":"string"},"description":"A list of strings that can be used to find other metadata about this DrsObject from external metadata sources. These aliases can be used to represent secondary accession numbers or external GUIDs.\n"}}},"DrsErrorResponse":{"properties":{"msg":{"type":"string"},"status_code":{"type":"number"}},"additionalProperties":false},"CandidateDrsObject":{"required":["name","size","checksums","mime_type"],"type":"object","properties":{"name":{"type":"string","description":"A string that can be used to name a DrsObject. This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_].\n"},"size":{"type":"integer","description":"For blobs, the blob size in bytes. For bundles, the cumulative size, in bytes, of items in the contents field.\n","format":"int64"},"mime_type":{"type":"string","description":"A string providing the mime-type of the DrsObject."},"checksums":{"type":"array","items":{"$ref":"#/components/schemas/Checksum"},"description":"The checksum of the DrsObject. At least one checksum must be provided. For blobs, the checksum is computed over the bytes in the blob. For bundles, the checksum is computed over a sorted concatenation of the checksums of its top-level contained objects (not recursive, names not included). The list of checksums is sorted alphabetically (hex-code) before concatenation and a further checksum is performed on the concatenated checksum value. For example, if a bundle contains blobs with the following checksums: md5(blob1) = 72794b6d md5(blob2) = 5e089d29 Then the checksum of the bundle is: md5( concat( sort( md5(blob1), md5(blob2) ) ) ) = md5( concat( sort( 72794b6d, 5e089d29 ) ) ) = md5( concat( 5e089d29, 72794b6d ) ) = md5( 5e089d2972794b6d ) = f7a29a04\n"},"access_methods":{"type":"array","items":{"$ref":"#/components/schemas/AccessMethod"},"description":"The list of access methods that can be used to fetch the DrsObject. Required for single blobs; optional for bundles.\n"},"description":{"type":"string","description":"A human readable description of the DrsObject."}}},"RegisterDrsObjectsRequest":{"required":["candidates"],"type":"object","properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/CandidateDrsObject"},"description":"A list of candidate DRS Objects to register."}}},"DrsUploadRequestObject":{"required":["name","size","mime_type","checksums"],"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","format":"int64"},"mime_type":{"type":"string"},"checksums":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/Checksum"}},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}}},"DrsUploadRequest":{"required":["objects"],"type":"object","properties":{"objects":{"type":"array","items":{"$ref":"#/components/schemas/DrsUploadRequestObject"}}}},"DrsUploadMethodType":{"enum":["s3","https"],"type":"string"},"DrsUploadMethod":{"required":["type","access_url","credentials"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/DrsUploadMethodType"},"access_url":{"$ref":"#/components/schemas/AccessUrl"},"region":{"type":"string"},"credentials":{"type":"object","additionalProperties":{"type":"string"}}}},"DrsUploadResponseObject":{"required":["id","self_uri","name","size","mime_type","checksums"],"type":"object","properties":{"id":{"type":"string","format":"uuid"},"self_uri":{"type":"string"},"name":{"type":"string"},"size":{"type":"integer","format":"int64"},"mime_type":{"type":"string"},"checksums":{"minItems":1,"type":"array","items":{"$ref":"#/components/schemas/Checksum"}},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"upload_methods":{"type":"array","items":{"$ref":"#/components/schemas/DrsUploadMethod"}}}},"DrsUploadResponse":{"required":["objects"],"type":"object","properties":{"objects":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DrsUploadResponseObject"}}}},"JsonPatchOperation":{"required":["op","path"],"type":"object","properties":{"op":{"enum":["add","remove","replace","move","copy","test"],"type":"string","description":"JSON Patch operation."},"path":{"type":"string","description":"JSON Pointer path to the element being changed.","example":"/status"},"value":{"description":"Value to apply for add/replace/test operations."},"from":{"type":"string","description":"Source path for move/copy operations."}},"additionalProperties":false,"description":"A single JSON Patch operation. For simple status updates, use: { \"op\": \"replace\", \"path\": \"/status\", \"value\": \"completed\" }.\n"}},"responses":{"BadRequest":{"description":"400 - Bad Request. The request could not be understood or was missing required parameters.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"Unauthorized":{"description":"401 - Unauthorized. Authentication is required or has failed.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"Forbidden":{"description":"403 - Forbidden. You do not have permission to access this resource.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"NotFound":{"description":"404 - Not Found. The resource ID does not exist.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}},"ServerError":{"description":"500 - Internal Server Error.","content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/FhirOperationOutcome"}}}}},"securitySchemes":{"app-level0":{"$ref":"https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level0"},"app-level3":{"$ref":"https://proxygen.prod.api.platform.nhs.uk/components/securitySchemes/app-level3"}}},"security":[{"app-level3":[]}]}