drug-discovery-prompts/upstream/K-Dense-AI-scientific-agent-skills/skills/database-lookup/references/uniprot.md

title, task, lineage_type, upstream_source, upstream_sha, imported_at, prompt_class, upstream_changes, author, validated

title	task	lineage_type	upstream_source	upstream_sha	imported_at	prompt_class	upstream_changes	author	validated
UniProt REST API		import	https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/uniprot.md	9c9bd2e9	2026-06-26	prompt	accepted	upstream	false

UniProt REST API

Base URL

https://rest.uniprot.org

Authentication

No API key required. All endpoints are public.

Key Endpoints

1. Search proteins

GET /uniprotkb/search

Parameters:

Parameter	Type	Description
query	string	Required. Search query using UniProt query syntax (field:value pairs, boolean operators).
format	string	json (default), tsv, fasta, xml, list, xlsx, obo
fields	string	Comma-separated list of columns to return. Key fields: accession, id, protein_name, gene_names, organism_name, organism_id, length, sequence, cc_function, go_id, go, xref_pdb, reviewed, ec, cc_subcellular_location, ft_domain, lineage
size	int	Results per page (max 500, default 25)
cursor	string	Pagination cursor (returned in Link response header)
sort	string	Sort field and direction, e.g. gene asc, length desc, annotation_score desc

Example calls:

Search for reviewed human TP53:

https://rest.uniprot.org/uniprotkb/search?query=(gene:TP53) AND (organism_id:9606) AND (reviewed:true)&format=json&fields=accession,protein_name,gene_names,organism_name,length,cc_function&size=10

Search by protein name keyword:

https://rest.uniprot.org/uniprotkb/search?query=(protein_name:insulin) AND (reviewed:true)&format=json&size=5

Search by EC number (enzyme classification):

https://rest.uniprot.org/uniprotkb/search?query=(ec:2.7.11.1) AND (organism_id:9606)&format=json&size=25

Search by Gene Ontology:

https://rest.uniprot.org/uniprotkb/search?query=(go:0006915) AND (organism_id:9606) AND (reviewed:true)&format=json&size=25

Response (JSON):

{
  "results": [
    {
      "entryType": "UniProtKB reviewed (Swiss-Prot)",
      "primaryAccession": "P04637",
      "uniProtkbId": "P53_HUMAN",
      "organism": {
        "scientificName": "Homo sapiens",
        "taxonId": 9606
      },
      "proteinDescription": {
        "recommendedName": {
          "fullName": { "value": "Cellular tumor antigen p53" }
        }
      },
      "genes": [
        {
          "geneName": { "value": "TP53" },
          "synonyms": [{ "value": "P53" }]
        }
      ],
      "sequence": {
        "value": "MEEPQSDP...",
        "length": 393,
        "molWeight": 43653,
        "crc64": "..."
      },
      "comments": [...],
      "features": [...],
      "references": [...]
    }
  ]
}

Pagination: The Link response header contains the next page URL with the cursor parameter. Follow it to get subsequent pages.

---

2. Fetch single entry by accession

GET /uniprotkb/{accession}

Parameters:

Parameter	Type	Description
format	string	json, tsv, fasta, xml, gff

Example calls:

https://rest.uniprot.org/uniprotkb/P04637?format=json
https://rest.uniprot.org/uniprotkb/P04637.fasta

---

3. FASTA sequence retrieval

Append .fasta to the accession or use format=fasta:

https://rest.uniprot.org/uniprotkb/P04637.fasta

Batch FASTA from search:

https://rest.uniprot.org/uniprotkb/search?query=(gene:BRCA1) AND (organism_id:9606) AND (reviewed:true)&format=fasta

---

4. ID Mapping (convert between ID types)

ID mapping is a two-step async process.

Step 1: Submit job

POST /idmapping/run
Content-Type: application/x-www-form-urlencoded

from={dbFrom}&to={dbTo}&ids={comma-separated-ids}

Common from/to database names:

• UniProtKB_AC-ID (UniProt accession)
• Gene_Name
• GeneID (NCBI Gene / Entrez Gene)
• Ensembl, Ensembl_Genomes
• RefSeq_Protein
• PDB
• ChEMBL
• EMBL-GenBank-DDBJ
• STRING

Returns:

{ "jobId": "abc123def456" }

Step 2: Poll and retrieve results

GET /idmapping/status/{jobId}

When complete, redirects to:

GET /idmapping/results/{jobId}?format=json&size=500

Example:

Map Ensembl gene IDs to UniProt accessions:

POST /idmapping/run
from=Ensembl&to=UniProtKB_AC-ID&ids=ENSG00000141510,ENSG00000012048

Map UniProt to PDB:

POST /idmapping/run
from=UniProtKB_AC-ID&to=PDB&ids=P04637,P38398

Response (results):

{
  "results": [
    {
      "from": "ENSG00000141510",
      "to": {
        "primaryAccession": "P04637",
        "uniProtkbId": "P53_HUMAN",
        ...
      }
    }
  ]
}

---

5. UniRef (clustered sequences)

GET /uniref/search?query={query}&format=json
GET /uniref/{id}

Cluster IDs: UniRef100_P04637, UniRef90_P04637, UniRef50_P04637

---

6. UniParc (sequence archive)

GET /uniparc/search?query={query}&format=json
GET /uniparc/{upi}

---

7. Proteomes

GET /proteomes/search?query=(organism_id:9606)&format=json
GET /proteomes/{upid}

Example — human reference proteome:

https://rest.uniprot.org/proteomes/UP000005640?format=json

---

8. Taxonomy

GET /taxonomy/search?query={query}&format=json
GET /taxonomy/{taxonId}

---

Query Syntax

UniProt search queries support field:value syntax with boolean operators:

• (gene:TP53) -- gene name
• (organism_id:9606) -- NCBI taxonomy ID (9606 = human, 10090 = mouse)
• (organism_name:"Homo sapiens") -- organism name
• (reviewed:true) -- Swiss-Prot only (manually reviewed)
• (protein_name:kinase) -- protein name contains keyword
• (ec:2.7.11.1) -- enzyme classification
• (go:0006915) -- Gene Ontology term ID
• (xref:pdb-P04637) -- cross-reference
• (length:[100 TO 300]) -- sequence length range
• (cc_disease:cancer) -- disease involvement
• (ft_domain:SH2) -- domain annotation
• (cc_subcellular_location:nucleus) -- subcellular location
• (date_modified:[2024-01-01 TO *]) -- modification date

Combine with AND, OR, NOT:

(gene:BRCA1) AND (organism_id:9606) AND (reviewed:true)

Rate Limits

• No hard published rate limit, but excessive requests will be throttled.
• Use pagination (size + cursor) to batch results.
• Batch ID mapping jobs instead of one-at-a-time lookups.
• For large downloads, use the streaming endpoints or FTP site.
• Respect Retry-After headers if you receive HTTP 429.

Error Format

{
  "url": "https://rest.uniprot.org/...",
  "messages": ["Error message here"]
}

HTTP 400 for bad queries, 404 for not found, 429 for rate limiting, 500 for server errors.