RNAcentral API

https://rnacentral.org/api
Admin
RNAcentral API is a RESTful web service providing programmatic access to RNAcentral's collection of...
Tokens:5,806
Snippets:40
Trust Score:9.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Example response with multiple entries

Source: https://rnacentral.org/api

Shows the JSON structure returned by the RNAcentral API when a request returns multiple entries. Includes pagination fields 'next' and 'previous', and a 'results' array. The example URL is https://rnacentral.org/api/v1/rna/.

```json
https://rnacentral.org/api/v1/rna/
{
    "next": "https://rnacentral.org/api/v1/rna/?page=2",
    "previous": null,
    "results": [
        {
            "url": "https://rnacentral.org/api/v1/rna/URS0000000001",
            "rnacentral_id": "URS0000000001",
            "md5": "06808191a979cc0b933265d9a9c213fd",
            "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
            "length": 66,
            "xrefs": "https://rnacentral.org/api/v1/rna/URS0000000001/xrefs"
        },

        // 9 more entries
    ]
}
```

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

### Example response with a single entry

Source: https://rnacentral.org/api

Shows the JSON structure returned by the RNAcentral API when a request returns a single entry. It does not include the pagination fields 'next' and 'previous'. The example URL is https://rnacentral.org/api/v1/rna/URS0000000001.

```json
https://rnacentral.org/api/v1/rna/URS0000000001
{
    "url": "https://rnacentral.org/api/v1/rna/URS0000000001",
    "rnacentral_id": "URS0000000001",
    "md5": "06808191a979cc0b933265d9a9c213fd",
    "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
    "length": 66,
    "xrefs": "https://rnacentral.org/api/v1/rna/URS0000000001/xrefs"
}
```

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

### Response to API root GET request

Source: https://rnacentral.org/api/current/?format=api

The HTTP 200 OK response to the GET request, including headers and JSON body with the RNA endpoint URL.

```http
HTTP 200 OK
    Content-Type: text/html; charset=utf-8
    Vary: Accept
    Allow: GET, HEAD, OPTIONS
    
    
{
    "rna": "https://rnacentral.org/api/v1/rna?format=api"
}
```

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

### Hyperlinked xrefs field example

Source: https://rnacentral.org/api

Shows the default representation of the 'xrefs' field as a hyperlink in the RNA object. This is the hyperlinked format.

```json
"xrefs": "https://rnacentral.org/api/v1/rna/URS0000000001/xrefs/"
```

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

### GET request to API root

Source: https://rnacentral.org/api/current/?format=api

Make a GET request to the RNAcentral API root endpoint with the format parameter set to 'api'.

```http
GET /api/current/?format=api
```

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

### GET /api/current/

Source: https://rnacentral.org/api/current/

Retrieves the API root resource, which contains a link to the RNA sequences endpoint. This is the entry point for the RNAcentral API Version 1.

```APIDOC
## GET /api/current/

### Description
Retrieves the API root resource, which provides a link to the RNA sequences endpoint. This is the entry point for the RNAcentral API Version 1.

### Method
GET

### Endpoint
/api/current/

### Response
#### Success Response (200)
- **rna** (string) - URL to the RNA sequences endpoint.

#### Response Example
{
    "rna": "https://rnacentral.org/api/v1/rna"
}
```

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

### GET /api/current/ - API root request

Source: https://rnacentral.org/api/current/

Makes a GET request to the RNAcentral API root endpoint. The response is returned in a machine-readable format when requested programmatically.

```http
GET /api/current/
```

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

### GET /api/current/

Source: https://rnacentral.org/api/current/?format=api

Retrieves the API root resource, which provides a link to the main RNA endpoint. This endpoint is used to discover the base URL for accessing RNA data.

```APIDOC
## [GET] /api/current/

### Description
Retrieves the API root resource, which provides a link to the main RNA endpoint. This endpoint is used to discover the base URL for accessing RNA data.

### Method
GET

### Endpoint
/api/current/

### Parameters
#### Query Parameters
- **format** (string) - Optional - Response format. Can be `api` or `json`.

### Request Example
```
GET /api/current/?format=api
```

### Response
#### Success Response (200)
- **rna** (string) - URL to the RNA collection endpoint.

#### Response Example
```
HTTP 200 OK
Content-Type: text/html; charset=utf-8
Vary: Accept
Allow: GET, HEAD, OPTIONS

{
    "rna": "https://rnacentral.org/api/v1/rna?format=api"
}
```
```

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

### GET /api/v1/rna/ - Combined filters

Source: https://rnacentral.org/api

Combine multiple filtering parameters using the `&` separator, which acts as a logical AND operator, to narrow down query results.

```APIDOC
## GET /api/v1/rna/

### Description
Combine any filters (e.g., length-based and external ID) using the `&` separator to narrow down the query. The separator acts as a logical AND operator.

### Method
GET

### Endpoint
/api/v1/rna/

### Parameters
#### Query Parameters
- **min_length** (integer) - Optional - Minimum sequence length.
- **max_length** (integer) - Optional - Maximum sequence length.
- **external_id** (string) - Optional - External ID to filter by.

### Request Example
https://rnacentral.org/api/v1/rna/?min_length=10&max_length=100

### Response
#### Success Response (200)
Returns filtered RNAcentral search results.

#### Response Example
(Not provided in source)
```

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

### GET /api/v1/rna/{id}?format=jsonp

Source: https://rnacentral.org/api

Retrieves RNA data for a given RNAcentral identifier using JSONP for cross-domain requests in JavaScript applications.

```APIDOC
## GET /api/v1/rna/{id}?format=jsonp

### Description
Retrieves RNA data for a given RNAcentral identifier. This endpoint supports JSONP for cross-domain requests in JavaScript applications.

### Method
GET

### Endpoint
https://rnacentral.org/api/v1/rna/{id}?format=jsonp

### Parameters
#### Path Parameters
- **id** (string) - Required - The RNAcentral identifier (e.g., URS0000000001).

#### Query Parameters
- **format** (string) - Required - Set to `jsonp` to enable JSONP.

### Request Example
$.ajax({
    url: 'https://rnacentral.org/api/v1/rna/URS0000000001?format=jsonp',
    dataType: 'jsonp',
    jsonp: false,
    jsonpCallback: 'callback',
    success: function(data){
        // do something with the data
        console.log(data.rnacentral_id + ', ' + data.sequence);
    },
});

### Response
#### Success Response (200)
Returns a JSONP response containing RNA data, including fields such as `rnacentral_id` and `sequence`.

```

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

### GET /api/v1/rna/

Source: https://rnacentral.org/api

Retrieves a paginated list of RNA entries. The response includes navigation fields (next, previous) and a results array containing RNA objects. Use the flat=true parameter to include nested objects inline.

```APIDOC
## GET /api/v1/rna/

### Description
Retrieves a paginated list of RNA entries. The response includes navigation fields (next, previous) and a results array containing RNA objects. Use the flat=true parameter to include nested objects inline.

### Method
GET

### Endpoint
https://rnacentral.org/api/v1/rna/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.
- **flat** (boolean) - Optional - When true, nested objects are included inline instead of as hyperlinks.

### Response
#### Success Response (200)
- **next** (string) - URL to the next page of results, or null if there is no next page.
- **previous** (string) - URL to the previous page of results, or null if there is no previous page.
- **results** (array) - Array of RNA objects.

#### Response Example
{
    "next": "https://rnacentral.org/api/v1/rna/?page=2",
    "previous": null,
    "results": [
        {
            "url": "https://rnacentral.org/api/v1/rna/URS0000000001",
            "rnacentral_id": "URS0000000001",
            "md5": "06808191a979cc0b933265d9a9c213fd",
            "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
            "length": 66,
            "xrefs": "https://rnacentral.org/api/v1/rna/URS0000000001/xrefs"
        }
    ]
}
```

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

### GET /api/v1/overlap/region/{species}/{region}

Source: https://rnacentral.org/api

Retrieves annotations based on genomic coordinates for a specified species. The response is similar to the Ensembl REST API and can be used with the Genoverse genome browser.

```APIDOC
## GET /api/v1/overlap/region/{species}/{region}

### Description
Retrieves annotations based on genomic coordinates for a specified species. The response content is similar to that provided by the Ensembl REST API and can be directly used to visualise the data using the Genoverse HTML5 genome browser.

### Method
GET

### Endpoint
https://rnacentral.org/api/v1/overlap/region/{species}/{region}

### Parameters
#### Path Parameters
- **species** (string) - Required - The species name (e.g., homo_sapiens).
- **region** (string) - Required - The genomic location in the format `chromosome:start-end`, may contain optional commas (e.g., 2:39,745,816-39,826,679).

### Request Example
GET https://rnacentral.org/api/v1/overlap/region/homo_sapiens/2:39,745,816-39,826,679

### Response
#### Success Response (200)
Returns annotations for the specified genomic region. The response format is similar to the Ensembl REST API overlap/region endpoint.

```

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

### GET /api/v1/rna/ - Filter by sequence length

Source: https://rnacentral.org/api

Filter RNAcentral search results by sequence length using the length, min_length, and max_length query parameters. These parameters can be used individually or combined to narrow results.

```APIDOC
## GET /api/v1/rna/

### Description
Filter RNAcentral search results by sequence length. The `length` parameter matches exact length, `min_length` matches sequences with length greater than or equal to the value, and `max_length` matches sequences with length less than or equal to the value.

### Method
GET

### Endpoint
/api/v1/rna/

### Parameters
#### Query Parameters
- **length** (integer) - Optional - Exact sequence length to filter by.
- **min_length** (integer) - Optional - Minimum sequence length (greater or equal).
- **max_length** (integer) - Optional - Maximum sequence length (less or equal).

### Request Example
https://rnacentral.org/api/v1/rna/?length=2014

### Response
#### Success Response (200)
Returns filtered RNAcentral search results.

#### Response Example
(Not provided in source)
```

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

### jQuery JSONP request to RNAcentral API

Source: https://rnacentral.org/api

Use this jQuery AJAX call to make a cross-domain request to the RNAcentral API. The example uses the jsonp data type with a custom callback function, and logs the RNAcentral ID and sequence to the console.

```javascript
$.ajax({
    url: 'https://rnacentral.org/api/v1/rna/URS0000000001?format=jsonp',
    dataType: 'jsonp',
    jsonp: false,
    jsonpCallback: 'callback',
    success: function(data){
        // do something with the data
        console.log(data.rnacentral_id + ', ' + data.sequence);
    },
});
```

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

### GET /api/v1/rna/{rnacentral_id}/

Source: https://rnacentral.org/api

Retrieves a single RNA entry by its RNAcentral ID. The response contains the RNA object without pagination fields. Use the flat=true parameter to include nested objects inline.

```APIDOC
## GET /api/v1/rna/{rnacentral_id}/

### Description
Retrieves a single RNA entry by its RNAcentral ID. The response contains the RNA object without pagination fields. Use the flat=true parameter to include nested objects inline.

### Method
GET

### Endpoint
https://rnacentral.org/api/v1/rna/{rnacentral_id}/

### Parameters
#### Path Parameters
- **rnacentral_id** (string) - Required - The RNAcentral identifier (e.g., URS0000000001).

#### Query Parameters
- **flat** (boolean) - Optional - When true, nested objects are included inline instead of as hyperlinks.

### Response
#### Success Response (200)
- **url** (string) - URL to this RNA entry.
- **rnacentral_id** (string) - RNAcentral identifier.
- **md5** (string) - MD5 checksum of the sequence.
- **sequence** (string) - RNA sequence.
- **length** (integer) - Length of the sequence.
- **xrefs** (string) - URL to cross-references for this RNA entry.

#### Response Example
{
    "url": "https://rnacentral.org/api/v1/rna/URS0000000001",
    "rnacentral_id": "URS0000000001",
    "md5": "06808191a979cc0b933265d9a9c213fd",
    "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
    "length": 66,
    "xrefs": "https://rnacentral.org/api/v1/rna/URS0000000001/xrefs"
}
```

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

### GET /api/v1/rna/ - Filter by external ID

Source: https://rnacentral.org/api

Filter RNAcentral search results by an external ID assigned to a sequence in one of the Expert Databases. The external ID is specified using the `external_id` query parameter.

```APIDOC
## GET /api/v1/rna/

### Description
Filter RNAcentral search results by an external ID, which is an identifier assigned to a sequence in one of the Expert Databases and imported into RNAcentral as a cross-reference.

### Method
GET

### Endpoint
/api/v1/rna/

### Parameters
#### Query Parameters
- **external_id** (string) - Required - The external ID to filter by.

### Request Example
https://rnacentral.org/api/v1/rna/?external_id=MIMAT0000091

### Response
#### Success Response (200)
Returns filtered RNAcentral search results.

#### Response Example
(Not provided in source)
```

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

### curl commands using Accept headers to specify output format

Source: https://rnacentral.org/api

Use these curl commands to request different output formats (JSON, FASTA, YAML, HTML) via the Accept header. Each command targets the same RNA sequence endpoint.

```bash
curl -H "Accept: application/json" https://rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: text/fasta" https://rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: application/yaml" https://rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: text/html" https://rnacentral.org/api/v1/rna/URS0000000001
```

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

### Output Formats

Source: https://rnacentral.org/api

All endpoints support multiple output formats: JSON, JSONP, YAML, HTML. Individual RNA sequences can also be downloaded in FASTA format. Formats can be specified via the 'format' URL parameter, a file extension suffix, or Accept headers.

```APIDOC
## Output Formats

### Description
The following output formats are supported for all endpoints: **JSON**, **JSONP** (for cross-origin Javascript requests), **YAML**, **HTML**. In addition, the data for individual RNA sequences can be downloaded in **FASTA** format.

### Format Specification Methods

#### 1. `format` URL Parameter
- `https://rnacentral.org/api/v1/rna/URS0000000001/?format=json`
- `https://rnacentral.org/api/v1/rna/URS0000000001/?format=fasta`
- `https://rnacentral.org/api/v1/rna/URS0000000001/?format=yaml`
- `https://rnacentral.org/api/v1/rna/URS0000000001/?format=api`

#### 2. `.format` Suffix
- `https://rnacentral.org/api/v1/rna/URS0000000001.json`
- `https://rnacentral.org/api/v1/rna/URS0000000001.fasta`
- `https://rnacentral.org/api/v1/rna/URS0000000001.yaml`
- `https://rnacentral.org/api/v1/rna/URS0000000001.api`

#### 3. Accept Headers
```
curl -H "Accept: application/json" https://rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: text/fasta" https://rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: application/yaml" https://rnacentral.org/api/v1/rna/URS0000000001
curl -H "Accept: text/html" https://rnacentral.org/api/v1/rna/URS0000000001
```

### Error Handling
In case there is a conflict between the Accept headers and the format parameter, an error message is returned, for example:
```
curl -H "Accept: application/json" https://rnacentral.org/api/v1/?format=yaml
or
curl -H "Accept: application/yaml" http://127.0.0.1:8000/api/v1/?format=json
{
  "detail": "Could not satisfy the request's Accept header"
}
```
```

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

### Pagination

Source: https://rnacentral.org/api

Responses containing multiple entries are paginated. Use the 'page' parameter to navigate between pages and 'page_size' to control the number of entries per page (default 10, max 100).

```APIDOC
## Pagination

### Description
Responses containing multiple entries are paginated to prevent accidental downloads of large amounts of data and to speed up the API. To navigate between pages, specify the `page` parameter. The page size is controlled by the `page_size` parameter. Its default value is **10 entries per page**, and the maximum number of entries per page is **100**.

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number to retrieve.
- **page_size** (integer) - Optional - Number of entries per page. Default is 10, maximum is 100.

### Examples
- `https://rnacentral.org/api/v1/rna/?page_size=5`
- `https://rnacentral.org/api/v1/rna/?page=2&page_size=5`
```

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

### HTTP 200 OK response for API root

Source: https://rnacentral.org/api/current/

Shows the response headers and JSON body returned by the API root endpoint. The response includes the 'rna' URL for accessing RNA data.

```http
HTTP 200 OK
    Content-Type: text/html; charset=utf-8
    Vary: Accept
    Allow: GET, HEAD, OPTIONS
    
    
{
    "rna": "https://rnacentral.org/api/v1/rna"
}
```

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

### curl commands showing Accept header conflict error

Source: https://rnacentral.org/api

These commands demonstrate the error returned when the Accept header conflicts with the format parameter. The output shows the JSON error message: "Could not satisfy the request's Accept header".

```bash
curl -H "Accept: application/json" https://rnacentral.org/api/v1/?format=yaml
or
curl -H "Accept: application/yaml" http://127.0.0.1:8000/api/v1/?format=json
```

```json
{
  "detail": "Could not satisfy the request's Accept header"
}
```
Tokens:
Raw