AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

database-lookup

Queries documented public database APIs with explicit endpoints, filters, pagination, and provenance. Used when a scientific, regulatory, financial, or other database-backed fact must be retrieved reproducibly from a named source rather than inferred from general knowledge.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--database-lookup at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 83

references/uniprot.md

UniProt REST API

Base URL

https://rest.uniprot.org

Identifier handling

UniProtKB accessions contain 6 or 10 alphanumeric characters under the official accession patterns; do not restrict them to P/Q plus five digits. Preserve the submitted accession and record the resolved primary accession when a secondary accession redirects. Isoform identifiers such as P04637-2 add a suffix and require an endpoint that supports isoforms; do not silently strip it and return the canonical sequence.

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}

Poll the status response until no longer running. Then request GET /idmapping/details/{jobId} and follow its redirectURL for the correct result resource. A typical result path is:

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

Example:

Map Ensembl gene IDs to UniProt accessions:

POST /idmapping/run
from=Ensembl&to=UniProtKB&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-4HHB) -- 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.

Mapping namespaces are directional: check https://rest.uniprot.org/configure/idmapping/fields for allowed from/to values. Preserve unmapped IDs and one-to-many mappings.