Skills › Scientific Agent Skills › database-lookup › pdb.md

pdb.md

123 lines · skills/database-lookup/references/pdb.md at 5f2bc03

Open on GitHub

1# RCSB Protein Data Bank (PDB) API Reference

RCSB Protein Data Bank (PDB) API Reference

Raw lines 1 to 2

3## Base URLs

4- **Data API**: `https://data.rcsb.org/rest/v1`

5- **Search API**: `https://search.rcsb.org/rcsbsearch/v2/query`

6- **GraphQL**: `https://data.rcsb.org/graphql`

7- **Files**: `https://files.rcsb.org`

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

Raw lines 3 to 8

9## Authentication

10None required. Fully public API.

Authentication

None required. Fully public API.

Raw lines 9 to 11

12## Rate Limits

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

Rate Limits

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

Raw lines 12 to 14

15## Key Endpoints

Key Endpoints

Raw lines 15 to 16

17### 1. Entry Lookup (Data API)

18```

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

20```

21Example:

22```

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

24```

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

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.

Raw lines 17 to 26

27### 2. Polymer Entity (unique molecular entity)

28```

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

30```

31Example:

32```

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

34```

36An entity may have multiple chain instances. For chain-specific coordinates/annotations use `/core/polymer_entity_instance/{entry_id}/{label_asym_id}`; `label_asym_id` is the mmCIF identifier, not necessarily the author chain ID.

2. Polymer Entity (unique molecular entity)

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

An entity may have multiple chain instances. For chain-specific coordinates/annotations use /core/polymer_entity_instance/{entry_id}/{label_asym_id}; label_asym_id is the mmCIF identifier, not necessarily the author chain ID.

Raw lines 27 to 37

38### 3. Assembly Info

39```

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

41```

3. Assembly Info

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

Raw lines 38 to 42

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

44```

45POST https://search.rcsb.org/rcsbsearch/v2/query

46Content-Type: application/json

47```

48Example — search by UniProt accession:

49```json

50{

51 "query": {

52 "type": "terminal",

53 "service": "text",

54 "parameters": {

55 "attribute": "rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers.database_accession",

56 "operator": "exact_match",

57 "value": "P69905"

58 }

59 },

60 "return_type": "entry"

61}

62```

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"
}

Raw lines 43 to 63

64### 5. Sequence Search (Search API)

65```json

66{

67 "query": {

68 "type": "terminal",

69 "service": "sequence",

70 "parameters": {

71 "evalue_cutoff": 0.1,

72 "identity_cutoff": 0.9,

73 "sequence_type": "protein",

74 "value": "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH"

75 }

76 },

77 "return_type": "polymer_entity"

78}

79```

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"
}

Raw lines 64 to 80

81### 6. Structure Similarity Search

82```json

83{

84 "query": {

85 "type": "terminal",

86 "service": "structure",

87 "parameters": {

88 "value": {"entry_id": "4HHB", "assembly_id": "1"},

89 "operator": "strict_shape_match"

90 }

91 },

92 "return_type": "assembly"

93}

94```

6. Structure Similarity Search

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

Raw lines 81 to 95

96### 7. Download Structure Files

97```

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

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

100```

101

7. Download Structure Files

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

Raw lines 96 to 101

102### 8. GraphQL Query

103```

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

105```

106Body example:

107```json

108{

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

110}

111```

112

8. GraphQL Query

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

Body example:

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

Raw lines 102 to 112

113## Response Format

114REST/Data and successful Search results return JSON. Search can return HTTP 204 for no matches; do not attempt to JSON-decode an empty body. File downloads return PDB/mmCIF text.

115

Response Format

REST/Data and successful Search results return JSON. Search can return HTTP 204 for no matches; do not attempt to JSON-decode an empty body. File downloads return PDB/mmCIF text.

Raw lines 113 to 115

116## Useful `return_type` Values for Search

117- `entry` — PDB IDs

118- `polymer_entity` — entity-level results (e.g., 4HHB_1)

119- `assembly` — biological assembly results

120

Useful `return_type` Values for Search

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

Raw lines 116 to 120

121## Notes

122- Search API uses POST with a JSON query DSL. Combine queries with `"type": "group"` and `"logical_operator": "and"/"or"`.

123- Pagination via `"request_options": {"paginate": {"start": 0, "rows": 25}}`.

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}}.

Raw lines 121 to 123