135 lines
3.2 KiB
Markdown
135 lines
3.2 KiB
Markdown
---
|
|
title: "RCSB Protein Data Bank (PDB) API Reference"
|
|
task: ""
|
|
lineage_type: import
|
|
upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/database-lookup/references/pdb.md
|
|
upstream_sha: 9c9bd2e9
|
|
imported_at: 2026-06-26
|
|
prompt_class: prompt
|
|
upstream_changes: accepted
|
|
author: upstream
|
|
validated: false
|
|
---
|
|
|
|
# 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:
|
|
```json
|
|
{
|
|
"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)
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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:
|
|
```json
|
|
{
|
|
"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}}`.
|