REST API

Most data in RNAcentral can be accessed programmatically using a RESTful API allowing for integration with other resources. The API implementation is based on the Django REST framework.

For an introduction, watch the webinar on the Rfam and RNAcentral APIs.

Web browsable API

The RNAcentral API is web browsable, which means that:

  • the data is served in either human- or computer-friendly formats depending on whether a URL is viewed in a browser or is retrieved programmatically;

  • many resources are hyperlinked so that it’s possible to navigate the API in the browser.

As a result, developers can familiarise themselves with the API and get a better sense of the RNAcentral data.

Browse the API →

Versioning

To ensure that changes in the RNAcentral API don’t break the applications relying on it, the API is versioned, and the version is included in the API’s URL.

For example, the current API is at Version 1 and is available at https://rnacentral.org/api/v1, and the next version will be available at https://rnacentral.org/api/v2.

The latest version of the API can be accessed at https://rnacentral.org/api/current, but it’s not recommended to use this endpoint for long-term development as the underlying data model may change.

No backward-incompatible changes are made to each version after it’s been made public. More specifically, it’s guaranteed that within one version there will be no:

  • changing urls

  • deleting or renaming data fields

  • changing data field types

The following non-disruptive changes may be implemented to a public API:

  • adding new endpoints

  • adding new data fields

  • adding new filtering methods

An advance notice will be given before obsoleting an API version. To stay up to date, please consider signing up for the RNAcentral updates.

Throttling

The maximum number of requests from the same IP address is limited to 5 requests per second for most endpoints, and 30 requests per minute for endpoints under /api/v1/rna/. Currently, there is no limit on the total number of requests from the same IP.

Please get in touch if you require a higher request rate.

Responsible automated access

RNAcentral is a free public resource. This guidance applies to scripts, crawlers, and AI agents, as well as other automated clients. It helps keep the service available to everyone.

Choose the appropriate access method

  • Use this REST API for targeted, programmatic lookups.

  • For whole datasets, release-scale analyses, or large ID mappings, first check the FTP bulk downloads, which lists the available files and formats, or the RNAcentral Hugging Face datasets. Do not reconstruct a release or download a large dataset by fetching individual API records.

  • AI assistants that support the RNAcentral MCP server should use it for natural-language research tasks instead of scraping HTML pages or coordinating many raw API calls.

  • Use the sequence-search API only for necessary similarity searches; it has separate submission limits.

Suggested request behaviour

These are suggested operating rates, not additional quota allocations. Do not exceed the enforced limits above.

Service

Suggested behaviour

Enforced limit

Most REST API endpoints

Keep sustained traffic at or below 1 request per second from one client/IP.

5 requests per second per IP

/api/v1/rna/ endpoints

Keep traffic below the limit; a conservative client makes no more than one request every 2 seconds.

30 requests per minute per IP

Sequence-search job submissions

Submit only required searches and do not retry immediately when the service is busy.

10 requests per minute per IP

In addition:

  • Cache responses where appropriate, reuse results, and narrow queries with filters before requesting more pages.

  • Request no more than 100 entries per page and fetch pages sequentially. Avoid flat=true unless nested data are needed, because those responses can take longer to generate.

  • On HTTP 429, honour Retry-After when it is present. Otherwise, use exponential backoff with jitter; do not retry concurrently or rotate IP addresses to bypass a limit.

  • Identify automated requests with a descriptive User-Agent, ideally including a contact URL or email address. Do not impersonate a browser or another client.

  • Do not scrape the website when a documented API, bulk download, or MCP tool provides the data. Follow applicable robots.txt rules when crawling public pages.

If your work needs more capacity, a different access pattern, or long-running automated access, please contact us before starting it.

API v1 documentation

The sections below document version 1 of the API, currently the only public version.

Example responses

Responses containing multiple entries have the following fields:

  • next and previous are urls to the corresponding results page

  • results is an array of entries.

Example: https://rnacentral.org/api/v1/rna/?md5=06808191a979cc0b933265d9a9c213fd

{
    "next": "https://rnacentral.org/api/v1/rna/?md5=06808191a979cc0b933265d9a9c213fd&page=2",
    "previous": null,
    "results": [
        {
            "url": "https://rnacentral.org/api/v1/rna/URS00002C9E9D",
            "rnacentral_id": "URS00002C9E9D",
            "md5": "06808191a979cc0b933265d9a9c213fd",
            "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
            "length": 66,
            "xrefs": "https://rnacentral.org/api/v1/rna/URS00002C9E9D/xrefs",
            "publications": "https://rnacentral.org/api/v1/rna/URS00002C9E9D/publications",
            "is_active": true,
            "description": "tRNA from 1 species",
            "rna_type": "tRNA",
            "count_distinct_organisms": 1,
            "distinct_databases": ["ENA"],
            "distinct_organisms": [7769]
        }
    ]
}

Responses containing just a single entry don’t have the extra navigation fields:

Example: https://rnacentral.org/api/v1/rna/URS00002C9E9D

{
    "url": "https://rnacentral.org/api/v1/rna/URS00002C9E9D",
    "rnacentral_id": "URS00002C9E9D",
    "md5": "06808191a979cc0b933265d9a9c213fd",
    "sequence": "CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA",
    "length": 66,
    "xrefs": "https://rnacentral.org/api/v1/rna/URS00002C9E9D/xrefs",
    "publications": "https://rnacentral.org/api/v1/rna/URS00002C9E9D/publications",
    "is_active": true,
    "description": "tRNA from 1 species",
    "rna_type": "tRNA",
    "count_distinct_organisms": 1,
    "distinct_databases": ["ENA"],
    "distinct_organisms": [7769]
}

Hyperlinked vs flat responses

Some objects are represented by hyperlinks, for example in the default RNA object cross-references are represented by a hyperlink:

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

Sometimes it is desirable to retrieve all nested objects in a single request, which can be done using the flat=true url parameter. Note that such requests may take longer.

Examples

Pagination

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. Use pages of up to 100 entries: larger pages are much slower and can time out.

Examples

Output formats

The following output formats are supported for all endpoints: JSON, YAML and HTML (the browsable API).

In addition, the data for individual RNA sequences can be downloaded in FASTA format.

There are three ways of specifying the format:

  1. format url parameter

  2. .format suffix

  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
    

If the Accept header and the format parameter conflict, the API returns HTTP status 406 with an error message, for example:

curl -H "Accept: application/json" "https://rnacentral.org/api/v1/rna/URS0000000001/?format=yaml"
{
  "detail": "Could not satisfy the request Accept header."
}

Filtering

The API supports several filtering operations that complement the main RNAcentral text search functionality.

Filtering by sequence length

There are 3 url parameters: length, min_length (greater or equal length), and max_length (less or equal length).

Examples

Filtering by external ids

The external id is an id assigned to a sequence in one of the Expert Databases, which is imported into RNAcentral as a cross-reference.

The external id can be specified by setting the external_id url parameter.

Examples

Filtering by MD5

Each sequence can be looked up by the MD5 hash of its uppercase DNA sequence using the md5 url parameter, as in the example script below.

Example: https://rnacentral.org/api/v1/rna/?md5=06808191a979cc0b933265d9a9c213fd

Combined filters

Any filters can be combined to narrow down the query using the & symbol as a separator, which acts as the logical AND operator.

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

Genome annotations

The API provides an endpoint for retrieving annotations based on genomic coordinates for a number of species.

The response content is similar to that provided by the Ensembl REST API and can be directly used to visualise the data in a genome browser.

The genome location should be in the chromosome:start-end format and may contain optional commas.

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

Example script

A common task is finding whether some sequence of interest has an RNAcentral id.

An example Python script for looking up RNAcentral unique sequence ids (URS) is provided below and can be used in more complicated programs.

Instead of sending the entire sequence over the network to the RNAcentral servers, the script only submits the md5 value calculated based on the sequence. The md5 value is 32 characters long and is unique for each sequence. Using md5 saves traffic and decreases the response time.

Additional notes:

  • all sequences are uppercase;

  • md5 is computed for DNA sequences (so all Us should be replaced with Ts).

import hashlib
import requests  # pip install requests

def get_md5(sequence):
    """
    Calculate md5 for an RNA sequence.
    """
    # RNAcentral stores DNA md5 hashes
    sequence = sequence.replace('U', 'T')
    sequence = ''.join(map(str, sequence)).encode('ascii')

    # get the md5 digest
    m = hashlib.md5()
    m.update(sequence)
    return m.hexdigest()

def get_rnacentral_id(md5):
    """
    Parse json output and return the RNAcentral id.
    """
    url = 'https://rnacentral.org/api/v1/rna'
    r = requests.get(url, params={'md5': md5})
    data = r.json()
    if len(data['results']) > 0:
        return data['results'][0]['rnacentral_id']
    else:
        return 'RNAcentral id not found'

# This sequence has an RNAcentral id
sequence = 'CUGAAUAAAUAAGGUAUCUUAUAUCUUUUAAUUAACAGUUAAACGCUUCCAUAAAGCUUUUAUCCA'
md5 = get_md5(sequence)
print(get_rnacentral_id(md5))  # URS00002C9E9D

# This sequence doesn't have an RNAcentral id
sequence = 'Not an RNA sequence'
md5 = get_md5(sequence)
print(get_rnacentral_id(md5))  # RNAcentral id not found

Cross-domain requests

Browsers only allow JavaScript on RNAcentral, EBI and a few partner sites to call the API directly. Web applications on other domains should request the data from their own server instead, or get in touch to have their domain added. JSONP is no longer supported.

Trailing slash

The trailing slash in all urls used in the API is optional, so https://rnacentral.org/api/v1/rna/URS00002C9E9D and https://rnacentral.org/api/v1/rna/URS00002C9E9D/ return the same entry.