Htsget Retrieval API Spec

https://samtools.github.io/hts-specs/
Admin
This specification describes the htsget protocol, a data retrieval API that bridges existing...
Tokens:10,190
Snippets:76
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example htsget Service-Info Response

Source: https://samtools.github.io/hts-specs/htsget.html

This JSON object demonstrates the expected structure and fields for an htsget service-info endpoint response, including htsget-specific capabilities.

```json
{
   "id":            "net.exampleco.htsget",
   "name":          "ExampleCo genomics data service",
   "version":       "0.1.0",
   "organization":  {
      "name":       "ExampleCo",
      "url":        "https://exampleco.com"
   },
   "type":  {
      "group":        "org.ga4gh",
      "artifact":     "htsget",
      "version":      "1.3.0"
   },
   "htsget": {
      "datatype": "reads",
      "formats":  ["BAM", "CRAM"],
      "fieldsParameterEffective": true,
      "tagsParametersEffective": false
   }
}

```

--------------------------------

### Example JSON Error Response

Source: https://samtools.github.io/hts-specs/htsget.html

A sample JSON response illustrating an error condition, including the error type and a descriptive message.

```json
{
   "htsget" : {
      "error": "NotFound",
      "message": "No such accession 'ENS16232164'"
   }
}

```

--------------------------------

### GET /reads/service-info

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Retrieves GA4GH Service Info, and htsget reads API features supported by the web service.

```APIDOC
## GET /reads/service-info

### Description
Retrieves GA4GH Service Info, and htsget reads API features supported by the web service.

### Method
GET

### Endpoint
/reads/service-info

### Response
#### Success Response (200)
- **htsgetServiceInfo** (object) - displays configuration of htsget service reads API

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### htsget API JSON Response Example

Source: https://samtools.github.io/hts-specs/htsget.html

This JSON object illustrates a typical response from the htsget API, detailing the format and URLs for retrieving data blocks.

```json
{
   "htsget" : {
      "format" : "BAM",
      "urls" : [
         {
            "url" : "data:application/vnd.ga4gh.bam;base64,QkFNAQ==",
            "class" : "header"
         },
         {
            "url" : "https://htsget.blocksrv.example/sample1234/header",
            "class" : "header"
         },
         {
            "url" : "https://htsget.blocksrv.example/sample1234/run1.bam",
            "headers" : {
               "Authorization" : "Bearer xxxx",
               "Range" : "bytes=65536-1003750"
             },
            "class" : "body"
         },
         {
            "url" : "https://htsget.blocksrv.example/sample1234/run1.bam",
            "headers" : {
               "Authorization" : "Bearer xxxx",
               "Range" : "bytes=2744831-9375732"
            },
            "class" : "body"
         }
      ]
   }
}

```

--------------------------------

### Example htsget Service Registry Registrations

Source: https://samtools.github.io/hts-specs/htsget.html

Illustrates how htsget reads and variants API endpoints should be registered in a service registry's `/services` endpoint. Each entry includes details like ID, name, description, URL, organization, and type.

```json
[
   {
      "id": "net.exampleco.htsget-reads",
      "name": "ExampleCo htsget reads API",
      "description": "Serves alignment data (BAM, CRAM) via htsget protocol",
      "version": "0.1.0",
      "url": "https://htsget.exampleco.com/v1/reads",
      "organization":  {
         "name":       "ExampleCo",
         "url":        "https://exampleco.com"
      },
      "type": {
         "group": "org.ga4gh",
         "artifact": "htsget",
         "version": "1.3.0"
      }
   },
   {
      "id": "net.exampleco.htsget-variants",
      "name": "ExampleCo htsget variants API",
      "description": "Serves variant data (VCF, BCF) via htsget protocol",
      "version": "0.1.0",
      "url": "https://htsget.exampleco.com/v1/variants"
      "organization":  {
         "name":       "ExampleCo",
         "url":        "https://exampleco.com"
      },
      "type": {
         "group": "org.ga4gh",
         "artifact": "htsget",
         "version": "1.3.0"
      }
   }
]

```

--------------------------------

### GET /variants/service-info

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Retrieves GA4GH Service Info, and htsget variants API features supported by the web service.

```APIDOC
## GET /variants/service-info

### Description
Retrieves GA4GH Service Info, and htsget variants API features supported by the web service.

### Method
GET

### Endpoint
/variants/service-info

### Response
#### Success Response (200)
- **htsgetServiceInfo** (object) - displays configuration of htsget service variants API

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Htsget POST Request Body Example

Source: https://samtools.github.io/hts-specs/htsget.html

This JSON object demonstrates the structure of a POST request body for an htsget server. It specifies the desired format, fields to include, tags to include and exclude, and multiple genomic regions for data retrieval.

```json
{
   "format" : "bam",
   "fields" : ["QNAME", "FLAG", "RNAME", "POS", "CIGAR", "SEQ"],
   "tags" : ["RG"],
   "notags" : ["OQ"],
   "regions" : [
      { "referenceName" : "chr1" },
      { "referenceName" : "chr2", "start" : 999, "end" : 1000 },
      { "referenceName" : "chr2", "start" : 2000, "end" : 2100 }
   ]
}
```

--------------------------------

### OAuth 2.0 Bearer Token Example

Source: https://samtools.github.io/hts-specs/htsget.html

When client authentication and/or authorization is required, clients must present an OAuth 2.0 bearer access token in the Authorization request header.

```http
Authorization: Bearer [access_token]

```

--------------------------------

### GET Endpoints for Reads and Variants

Source: https://samtools.github.io/hts-specs/htsget.html

Use these endpoints to access reads and variants data. The response is a ticket for obtaining data in a specified format.

```http
GET /reads/<id>
GET /variants/<id>

```

--------------------------------

### GET /variants/{id}

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Retrieves variants from a pre-indexed ID. Supports filtering by format, class, reference name, start/end positions, and tags.

```APIDOC
## GET /variants/{id}

### Description
Gets the variants from a pre-indexed id. Searches a pre-indexed object id.

### Method
GET

### Endpoint
/variants/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the pre-indexed object.

#### Query Parameters
- **format** (FormatVariants) - Optional - The desired output format for the variants.
- **class** (string) - Optional - The class of variants to retrieve.
- **referenceName** (string) - Optional - The reference sequence name.
- **start** (integer) - Optional - The start position for the query.
- **end** (integer) - Optional - The end position for the query.
- **tags** (TagsVariants) - Optional - Filters results based on specified tags.
- **notags** (NoTagsVariants) - Optional - Excludes results with specified tags.

### Responses
#### Success Response (200)
- **object** - Results matching the criteria.

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **500** - Internal Server Error
```

--------------------------------

### POST /variants

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Get an htsget ticket for variant data streaming. Servers may optionally accept POST requests to enable variant data streaming of more than one genomic region.

```APIDOC
## POST /variants

### Description
Get an htsget ticket for variant data streaming. Servers may optionally accept POST requests to enable variant data streaming of more than one genomic region.

### Method
POST

### Endpoint
/variants

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the data to retrieve.

#### Request Body
- **Specify output format, genomic regions, etc.** (object) - Optional

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **htsget** (object) - Container for response object
  - **format** (string) - Response data is in this format
  - **md5** (string) - MD5 digest of the blob resulting from concatenating all of the payload data
  - **urls** (array) - An array providing URLs from which raw variant data can be retrieved

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### GET /reads/{id}

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Retrieves genomic reads from a pre-indexed ID. Supports filtering by format, class, reference name, start/end positions, and tags.

```APIDOC
## GET /reads/{id}

### Description
Gets the reads from a pre-indexed id. Searches a pre-indexed object id.

### Method
GET

### Endpoint
/reads/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the pre-indexed object.

#### Query Parameters
- **format** (FormatReads) - Optional - The desired output format for the reads.
- **class** (string) - Optional - The class of reads to retrieve.
- **referenceName** (string) - Optional - The reference sequence name.
- **start** (integer) - Optional - The start position for the query.
- **end** (integer) - Optional - The end position for the query.
- **fields** (FieldsReads) - Optional - Specifies which fields to include in the response.
- **tags** (TagsReads) - Optional - Filters results based on specified tags.
- **notags** (NoTagsReads) - Optional - Excludes results with specified tags.

### Responses
#### Success Response (200)
- **htsgetResponseReads** (object) - Results matching the criteria.

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **500** - Internal Server Error
```

--------------------------------

### htsget Protocol Overview

Source: https://samtools.github.io/hts-specs/htsget.html

General information about how htsget API invocations are made, including request methods, response formats, and content negotiation.

```APIDOC
## Protocol Essentials

All API invocations are made to a configurable HTTP(S) endpoint, receive either URL-encoded query string parameters (GET) or a JSON request body (POST), and return JSON output. Successful requests result with HTTP status code 200 and have UTF8-encoded JSON in the response body. The server may provide responses with chunked transfer encoding. The client and server may mutually negotiate HTTP/2 upgrade using the standard mechanism.

The JSON response is an object with the single key `htsget` as described in the Response JSON fields and Error Response JSON fields sections. This ensures that, apart from whitespace differences, the message always starts with the same prefix. The presence of this prefix can be used as part of a client’s response validation.

Any timestamps that appear in the response from an API method are given as ISO 8601 date/time format.

HTTP responses may be compressed using RFC 2616 `transfer-coding`, not `content-coding`.

Requests adhering to this specification MAY include an `Accept` header specifying the htsget protocol version they are using:
```
Accept: application/vnd.ga4gh.htsget.v1.0.0+json
```

JSON responses SHOULD include a `Content-Type` header describing the htsget protocol version defining the JSON schema used in the response, e.g.,
```
Content-Type: application/vnd.ga4gh.htsget.v1.0.0+json; charset=utf-8
```
```

--------------------------------

### Accept Header for htsget Protocol Version

Source: https://samtools.github.io/hts-specs/htsget.html

Clients can specify the htsget protocol version they are using by including an 'Accept' header in their requests.

```http
Accept: application/vnd.ga4gh.htsget.v1.0.0+json

```

--------------------------------

### htsget Query Parameters

Source: https://samtools.github.io/hts-specs/htsget.html

This section details the query parameters available for htsget requests, allowing clients to customize data retrieval.

```APIDOC
## Query Parameters

### `format`
_optional string_
Request data in this format. The allowed values for each type of record are:
  * Reads: BAM (default), CRAM.
  * Variants: VCF (default), BCF.

The server SHOULD reply with an `UnsupportedFormat` error if the requested format is not supported.

### `class`
_optional string_
Request different classes of data. By default, i.e., when `class` is not specified, the response will represent a complete read or variant data stream, encompassing SAM/CRAM/VCF headers, body data records, and EOF marker. If `class` is specified, its value MUST be one of the following: |  `header` | Request the SAM/CRAM/VCF headers only. The ticket response represents read or variant headers in the format specified by `format`, if present, or in the respective default format. The server SHOULD respond with an `InvalidInput` error if any other htsget query parameters other than `format` are specified at the same time as `class=header`.

### `referenceName`
_optional_
The reference sequence name, for example “chr1”, “1”, or “chrX”. If unspecified, all records are returned regardless of position. For the reads endpoint: if “*”, unplaced unmapped reads are returned. If unspecified, all reads (mapped and unmapped) are returned. (_Unplaced unmapped_ reads are the subset of unmapped reads completely without location information, i.e., with RNAME and POS field values of “*” and 0 respectively. See the SAM specification for details of placed and unplaced unmapped reads.) The server SHOULD reply with a `NotFound` error if the requested reference does not exist.

### `start`
_optional 32-bit unsigned integer_
The start position of the range on the reference, 0-based, inclusive. The server SHOULD respond with an `InvalidInput` error if `start` is specified and either no reference is specified or `referenceName` is “*”. The server SHOULD respond with an `InvalidRange` error if `start` and `end` are specified and `start` is greater than `end`.

### `end`
_optional 32-bit unsigned integer_
The end position of the range on the reference, 0-based exclusive. The server SHOULD respond with an `InvalidInput` error if `end` is specified and either no reference is specified or `referenceName` is “*”. The server SHOULD respond with an `InvalidRange` error if `start` and `end` are specified and `start` is greater than `end`.

### `fields`
_optional_
A list of fields to include, see below. Default: all

### `tags`
_optional_
A comma separated list of tags to include, default: all. If the empty string is specified (tags=) no tags are included. The server SHOULD respond with an `InvalidInput` error if `tags` and `notags` intersect.

### `notags`
_optional_
A comma separated list of tags to exclude, default: none. The server SHOULD respond with an `InvalidInput` error if `tags` and `notags` intersect.

### Field filtering
The list of fields is based on BAM fields:
Field | Description  
---|---
QNAME | Read names  
FLAG | Read bit flags  
RNAME | Reference sequence name  
POS | Alignment position  
MAPQ | Mapping quality score  
CIGAR | CIGAR string  
RNEXT | Reference sequence name of the next fragment template  
PNEXT | Alignment position of the next fragment in the template  
TLEN | Inferred template size  
SEQ | Read bases  
QUAL | Base quality scores  
Example: `fields=QNAME,FLAG,POS`.
As with range filtering, a server may include more fields than explicitly requested, a possibility which clients must be prepared to handle. The `fieldsParameterEffective` attribute in the GA4GH service-info metadata (see below) indicates whether a server supports filtering individual fields. In any case, servers must not generate any response payload that is invalid under the respective format specification (for example, if a request for reads in BAM format includes `QUAL`, then the response must provide `SEQ` as well).
```

--------------------------------

### POST /reads/{id}

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Obtains an htsget ticket for streaming reads data. This method is useful for streaming alignment data for multiple genomic regions.

```APIDOC
## POST /reads/{id}

### Description
Get htsget ticket for reads data streaming. Servers may optionally accept `POST` requests to enable alignment data streaming of more than one genomic region.

### Method
POST

### Endpoint
/reads/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the pre-indexed object.

#### Request Body
- **RequestBodyReads** (object) - Optional - Specifies output format, fields, genomic regions, etc.

### Responses
#### Success Response (200)
- **htsgetResponseReads** (object) - Successfully retrieved ticket for streaming alignment file.

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
- **413** - Payload Too Large
- **500** - Internal Server Error
```

--------------------------------

### Service Info Metadata

Source: https://samtools.github.io/hts-specs/htsget.html

Retrieves GA4GH service-info metadata. This endpoint is reserved for this purpose.

```APIDOC
## GET /service-info

### Description
Retrieves GA4GH service-info metadata. This endpoint is reserved for this purpose.

### Method
GET

### Endpoint
/service-info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None explicitly documented.

### Response
#### Success Response (200)
GA4GH service-info metadata.

#### Response Example
None explicitly documented.
```

--------------------------------

### Common Error Responses

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

This section details the common error responses that can be returned by the htsget API. These include responses for bad requests, unauthorized access, forbidden actions, not found resources, payload too large, and internal server errors.

```APIDOC
## Common Error Responses

### Description
Details the standard error responses for the htsget API.

### Responses

- **400 Bad Request**: Returned for invalid input, unsupported formats, or invalid ranges.
  - Content: `application/json`
  - Schema: `UnsupportedFormatError`, `InvalidInputError`, `InvalidRangeError`

- **401 Unauthorized**: Returned when authentication is invalid.
  - Content: `application/json`
  - Schema: `InvalidAuthenticationError`

- **403 Forbidden**: Returned when the client does not have permission to access the resource.
  - Content: `application/json`
  - Schema: `PermissionDeniedError`

- **404 Not Found**: Returned when the requested resource does not exist.
  - Content: `application/json`
  - Schema: `NotFoundError`

- **413 Payload Too Large**: Returned when the request payload exceeds the server's limits.
  - Content: `application/json`
  - Schema: `PayloadTooLargeError`

- **500 Internal Server Error**: Returned for unexpected server-side errors.
  - Content: `application/json`
  - Schema: `InternalServerError`
```

--------------------------------

### htsget Error Handling

Source: https://samtools.github.io/hts-specs/htsget.html

Details on how the htsget protocol handles errors, including required HTTP status codes and the structure of JSON error responses.

```APIDOC
## Errors

The server MUST respond with an appropriate HTTP status code (4xx or 5xx) when an error condition is detected. In the case of transient server errors, (e.g., 503 and other 5xx status codes), the client SHOULD implement appropriate retry logic as discussed in Reliability & performance considerations below.

For errors that are specific to the `htsget` protocol, the response body SHOULD be a JSON object (content-type `application/json`) providing machine-readable information about the nature of the error, along with a human-readable description. The structure of this JSON object is described as follows.

### Error Response JSON fields
`htsget` _object_ |  Container for response object. |  `error`  
_string_ |  The type of error. This SHOULD be chosen from the list below.  
---|---  
`message`  
_string_ |  A message specific to the error providing information on how to debug the problem. Clients MAY display this message to the user.  

The following errors types are defined:
Error type | HTTP status code | Description  
---|---|---  
InvalidAuthentication | 401 | Authorization provided is invalid  
PermissionDenied | 403 | Authorization is required to access the resource  
NotFound | 404 | The resource requested was not found  
PayloadTooLarge | 413 | POST request size is too large  
UnsupportedFormat | 400 | The requested file format is not supported by the server  
InvalidInput | 400 | The request parameters do not adhere to the specification  
InvalidRange | 400 | The requested range cannot be satisfied  

The error type SHOULD be chosen from this table and be accompanied by the specified HTTP status code. An example of a valid JSON error response is:
```
{
   "htsget" : {
      "error": "NotFound",
      "message": "No such accession 'ENS16232164'"
   }
}
```
```

--------------------------------

### Reads Data Retrieval

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Retrieves alignment data (BAM or CRAM format). Supports specifying regions, desired SAM fields, tags to include, and tags to exclude. Can also request only the header.

```APIDOC
## GET /reads

### Description
Retrieves alignment data in BAM or CRAM format. Allows for specifying genomic regions, SAM fields, and tags for inclusion or exclusion. Can also be used to fetch only the header information.

### Method
GET

### Endpoint
/reads

### Parameters
#### Query Parameters
- **format** (FormatReads) - Optional - Desired alignment file format (BAM, CRAM).
- **class** (Class) - Optional - Request different classes of data, e.g., 'header'.
- **fields** (FieldsReads) - Optional - A list of SAM fields to include.
- **tags** (TagsReads) - Optional - A list of SAM tags to include.
- **notags** (NoTagsReads) - Optional - A list of SAM tags to exclude.

#### Request Body
- **regions** (array of Region) - Optional - A list of genomic regions to return. If not present, the entire file will be returned.
  - **referenceName** (string) - Required - Reference sequence name.
  - **start** (integer) - Optional - The start position of the range (0-based, inclusive).
  - **end** (integer) - Optional - The end position of the range (0-based exclusive).

### Request Example
```json
{
  "regions": [
    {
      "referenceName": "chr1",
      "start": 12312,
      "end": 99999
    }
  ],
  "format": "BAM",
  "fields": ["QNAME", "RNAME"],
  "tags": ["MD", "NM"]
}
```

### Response
#### Success Response (200)
- **htsgetUrl** (htsgetUrl) - URL to download data block, optionally with headers and class specification.

#### Response Example
```json
{
  "htsgetUrl": {
    "url": "https://htsget.blocksrv.example/sample1234/run1.bam",
    "headers": {
      "Authorization": "Bearer xxxxx",
      "Range": "bytes=65536-1003750"
    },
    "class": "body"
  }
}
```
```

--------------------------------

### POST Request for Genomic Data

Source: https://samtools.github.io/hts-specs/htsget.html

Servers may optionally accept POST requests to retrieve genomic data. This method allows for specifying multiple genomic ranges and custom fields in the request body. POST requests must be safe (read-only) and may have size limits.

```APIDOC
## POST /<htsget-endpoint>

### Description
Accepts POST requests to retrieve genomic data, supporting multiple regions and custom field filtering. This method is designed to be safe and read-only.

### Method
POST

### Endpoint
POST requests should use the same URLs as GET requests. Query parameters on the URL are not permitted for POST requests.

### Request Body
The request body is a JSON object containing the following parameters:

- **format** (string, optional): Request data in a specific format. Allowed values depend on the record type (e.g., BAM, CRAM for Reads; VCF, BCF for Variants).
- **class** (string, optional): Request different classes of data. Allowed values: `header` (requests headers only). If not specified, the full data stream is returned.
- **fields** (array of strings, optional): List of fields to include in the response. See Field filtering for details.
- **tags** (array of strings, optional): List of tags to include. Defaults to all tags. An empty array excludes all tags.
- **notags** (array of strings, optional): List of tags to exclude. Defaults to none.
- **regions** (array of objects, optional): Specifies the genomic regions to retrieve. If not present, the entire file is returned. Each object in the array must contain:
  - **referenceName** (string): The reference sequence name (e.g., "chr1").
  - **start** (unsigned integer, optional): The 0-based, inclusive start position.
  - **end** (unsigned integer, optional): The 0-based, exclusive end position.

### Request Example
```json
{
   "format" : "bam",
   "fields" : ["QNAME", "FLAG", "RNAME", "POS", "CIGAR", "SEQ"],
   "tags" : ["RG"],
   "notags" : ["OQ"],
   "regions" : [
      { "referenceName" : "chr1" },
      { "referenceName" : "chr2", "start" : 999, "end" : 1000 },
      { "referenceName" : "chr2", "start" : 2000, "end" : 2100 }
   ]
}
```

### Response
#### Success Response (200)
Returns a JSON "ticket" similar to the GET method, containing information about the requested data.

#### Response Example
(Response example not provided in source text)

### Error Handling
- **PayloadTooLarge**: If the incoming POST request is too large.
- **InvalidInput**: If query parameters are present on the URL, if `tags` and `notags` intersect, if `regions` is empty or not well-formed, or if `class` is "header" and other parameters besides `format` are specified.
- **UnsupportedFormat**: If the requested format is not supported.
- **NotFound**: If the requested reference does not exist.
```

--------------------------------

### Content-Type Header for htsget JSON Response

Source: https://samtools.github.io/hts-specs/htsget.html

Servers should include a 'Content-Type' header in JSON responses to indicate the htsget protocol version and character set.

```http
Content-Type: application/vnd.ga4gh.htsget.v1.0.0+json; charset=utf-8

```

--------------------------------

### Variants Data Retrieval

Source: https://samtools.github.io/hts-specs/pub/htsget-openapi.yaml

Retrieves variant data (VCF or BCF format). Supports specifying regions, tags to include, and tags to exclude. Can also request only the header.

```APIDOC
## GET /variants

### Description
Retrieves variant data in VCF or BCF format. Allows for specifying genomic regions and tags for inclusion or exclusion. Can also be used to fetch only the header information.

### Method
GET

### Endpoint
/variants

### Parameters
#### Query Parameters
- **format** (FormatVariants) - Optional - Desired variant file format (VCF, BCF).
- **class** (Class) - Optional - Request different classes of data, e.g., 'header'.
- **tags** (TagsVariants) - Optional - A list of tags to include.
- **notags** (NoTagsVariants) - Optional - A list of tags to exclude.

#### Request Body
- **regions** (array of Region) - Optional - A list of genomic regions to return. If not present, the entire file will be returned.
  - **referenceName** (string) - Required - Reference sequence name.
  - **start** (integer) - Optional - The start position of the range (0-based, inclusive).
  - **end** (integer) - Optional - The end position of the range (0-based exclusive).

### Request Example
```json
{
  "regions": [
    {
      "referenceName": "chr1",
      "start": 12312,
      "end": 99999
    }
  ],
  "format": "VCF"
}
```

### Response
#### Success Response (200)
- **htsgetUrl** (htsgetUrl) - URL to download data block, optionally with headers and class specification.

#### Response Example
```json
{
  "htsgetUrl": {
    "url": "https://example.com/sample1234/run1.vcf"
  }
}
```
```

--------------------------------

### Access Variants Data

Source: https://samtools.github.io/hts-specs/htsget.html

Retrieves variants data for a given ID. The response is a ticket that may require follow-on requests. Supports filtering by genomic range and requesting headers.

```APIDOC
## GET /variants/<id>

### Description
Retrieves variants data for a given ID. The response is a ticket that may require follow-on requests. Supports filtering by genomic range and requesting headers.

### Method
GET

### Endpoint
/variants/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - A string identifying which records to return. The format of this identifier is left to the discretion of the API provider, including allowing embedded "/" characters. Examples include VariantSetIds, Studies, Samples, or Runs.

#### Query Parameters
None explicitly documented.

#### Request Body
None

### Request Example
None explicitly documented.

### Response
#### Success Response (200)
A JSON response that is a "ticket" allowing the caller to obtain the desired data. The response may contain a superset of the desired results, and the client should filter out extraneous records if necessary. Successful requests with empty result sets still produce a valid response.

#### Response Example
None explicitly documented.
```

--------------------------------

### Access Reads Data

Source: https://samtools.github.io/hts-specs/htsget.html

Retrieves reads data for a given ID. The response is a ticket that may require follow-on requests. Supports filtering by genomic range and requesting headers.

```APIDOC
## GET /reads/<id>

### Description
Retrieves reads data for a given ID. The response is a ticket that may require follow-on requests. Supports filtering by genomic range and requesting headers.

### Method
GET

### Endpoint
/reads/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - A string identifying which records to return. The format of this identifier is left to the discretion of the API provider, including allowing embedded "/" characters. Examples include ReadGroupSetIds, Studies, Samples, or Runs.

#### Query Parameters
None explicitly documented.

#### Request Body
None

### Request Example
None explicitly documented.

### Response
#### Success Response (200)
A JSON response that is a "ticket" allowing the caller to obtain the desired data. The response may contain a superset of the desired results, and the client should filter out extraneous records if necessary. Successful requests with empty result sets still produce a valid response.

#### Response Example
None explicitly documented.
```
Tokens:
Raw