RCSB Protein Data Bank (PDB) API Reference

Base URLs

• Data API: https://data.rcsb.org/rest/v1
• Search API: https://search.rcsb.org/rcsbsearch/v2/query
• GraphQL: https://data.rcsb.org/graphql
• Files: https://files.rcsb.org

Authentication

None required. Fully public API.

Rate Limits

No published hard limits; be courteous (a few requests/second). Bulk downloads available via FTP.

Key Endpoints

1. Entry Lookup (Data API)

GET https://data.rcsb.org/rest/v1/core/entry/{entry_id}

Example:

GET https://data.rcsb.org/rest/v1/core/entry/4HHB

Returns JSON with resolution, method, deposition date, title, authors, etc.

2. Polymer Entity (chain-level info)

GET https://data.rcsb.org/rest/v1/core/polymer_entity/{entry_id}/{entity_id}

Example:

GET https://data.rcsb.org/rest/v1/core/polymer_entity/4HHB/1

3. Assembly Info

GET https://data.rcsb.org/rest/v1/core/assembly/{entry_id}/{assembly_id}

4. Full-Text and Attribute Search (Search API)

POST https://search.rcsb.org/rcsbsearch/v2/query
Content-Type: application/json

Example — search by UniProt accession:

{
  "query": {
    "type": "terminal",
    "service": "text",
    "parameters": {
      "attribute": "rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers.database_accession",
      "operator": "exact_match",
      "value": "P69905"
    }
  },
  "return_type": "entry"
}

5. Sequence Search (Search API)

{
  "query": {
    "type": "terminal",
    "service": "sequence",
    "parameters": {
      "evalue_cutoff": 0.1,
      "identity_cutoff": 0.9,
      "sequence_type": "protein",
      "value": "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH"
    }
  },
  "return_type": "polymer_entity"
}

6. Structure Similarity Search

{
  "query": {
    "type": "terminal",
    "service": "structure",
    "parameters": {
      "value": {"entry_id": "4HHB", "assembly_id": "1"},
      "operator": "strict_shape_match"
    }
  },
  "return_type": "assembly"
}

7. Download Structure Files

GET https://files.rcsb.org/download/{entry_id}.cif
GET https://files.rcsb.org/download/{entry_id}.pdb

8. GraphQL Query

POST https://data.rcsb.org/graphql

Body example:

{
  "query": "{ entry(entry_id: \\"4HHB\\") { rcsb_entry_info { resolution_combined } struct { title } } }"
}

Response Format

All REST/Search endpoints return JSON. File downloads return PDB/mmCIF text.

Useful return_type Values for Search

• entry — PDB IDs
• polymer_entity — entity-level results (e.g., 4HHB_1)
• assembly — biological assembly results

Notes

• Search API uses POST with a JSON query DSL. Combine queries with "type": "group" and "logical_operator": "and"/"or".
• Pagination via "request_options": {"paginate": {"start": 0, "rows": 25}}.