# 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](https://www.django-rest-framework.org/). For an introduction, watch the {ref}`webinar on the Rfam and RNAcentral APIs `. (web-browsable-api)= ## 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 →](https://rnacentral.org/api/v1) (versioning)= ## 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 , and the next version will be available at `https://rnacentral.org/api/v2`. The **latest version** of the API can be accessed at , 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](https://blog.rnacentral.org). (throttling)= ## 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](contact-us.md) if you require a higher request rate. (responsible-automated-access)= ## 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](downloads.md), which lists the available files and formats, or the [RNAcentral Hugging Face datasets](https://huggingface.co/datasets/RNAcentral). Do not reconstruct a release or download a large dataset by fetching individual API records. * AI assistants that support the [RNAcentral MCP server](rnacentral-mcp-server.md) should use it for natural-language research tasks instead of scraping HTML pages or coordinating many raw API calls. * Use the [sequence-search API](sequence-search-api.md) 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](sequence-search-api.md#api-throttling) | 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](contact-us.md) before starting it. ## API v1 documentation The sections below document **version 1** of the API, currently the only public version. (v1-example-responses)= ### 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:** ```json { "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:** ```json { "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] } ``` (v1-hyperlinked-vs-flat-responses)= #### Hyperlinked vs flat responses Some objects are represented by hyperlinks, for example in the default RNA object cross-references are represented by a hyperlink: ```json "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** * (hyperlinked) * (flat) * (hyperlinked) * (flat) (v1-pagination)= ### 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** * * (v1-output-formats)= ### 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept) ```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 ``` If the Accept header and the format parameter conflict, the API returns HTTP status `406` with an error message, for example: ```bash curl -H "Accept: application/json" "https://rnacentral.org/api/v1/rna/URS0000000001/?format=yaml" ``` ```json { "detail": "Could not satisfy the request Accept header." } ``` (v1-filtering)= ### Filtering The API supports several filtering operations that complement the main RNAcentral [text search](searching-rnacentral.md) functionality. (v1-filtering-by-sequence-length)= #### Filtering by sequence length There are 3 url parameters: `length`, `min_length` (greater or equal length), and `max_length` (less or equal length). **Examples** * * * * (v1-filtering-by-external-ids)= #### Filtering by external ids The external id is an id assigned to a sequence in one of the [Expert Databases](expert-databases.md), which is imported into RNAcentral as a cross-reference. The external id can be specified by setting the `external_id` url parameter. **Examples** * (SRPDB) * (miRBase) * (Vega) * (tmRNA Website) (v1-filtering-by-md5)= #### Filtering by MD5 Each sequence can be looked up by the [MD5](https://en.wikipedia.org/wiki/MD5) hash of its uppercase DNA sequence using the `md5` url parameter, as in the [example script](#v1-example-script) below. **Example:** (v1-combined-filters)= #### 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:** (genome-annotations)= ### Genome annotations The API provides an endpoint for retrieving annotations based on genomic coordinates for a [number of species](genome-browser.md). The response content is similar to that provided by the [Ensembl REST API](https://rest.ensembl.org/documentation/info/overlap_region) 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:** (v1-example-script)= ### 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](https://en.wikipedia.org/wiki/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). ```python 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 ``` (v1-cross-domain-requests)= ### 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](contact-us.md) to have their domain added. JSONP is no longer supported. (v1-trailing-slash)= ### Trailing slash The trailing slash in all urls used in the API is **optional**, so and return the same entry.