canonical: https://jentic.com/apis/data.rcsb.org/rcsb

# Data Rcsb RCSB RESTful API

Jentic publishes the only available OpenAPI specification for the RCSB RESTful API, keeping it validated and agent-ready. The Research Collaboratory for Structural Bioinformatics (RCSB) Protein Data Bank exposes structured access to the canonical archive of three-dimensional macromolecular structures used in life sciences research and drug discovery. The 39-endpoint API covers entries, assemblies, polymer and non-polymer entities, entity instances, chemical components, interfaces, groups, schema, and repository holdings. Endpoints are public and require no authentication.

## For AI agents

Retrieve protein structures, chemical components, polymer entities, interfaces, and groups from the RCSB Protein Data Bank for research and drug discovery workflows.

## Scope

Does not handle protein sequence search, structure prediction, or molecular dynamics simulation - use for retrieving published RCSB Protein Data Bank entries, entities, chemical components, interfaces, and groups only.

## Capabilities

- Retrieve a structure entry by PDB entry ID
- Fetch assembly descriptions for a given entry and assembly ID
- Retrieve polymer, non-polymer, and branched entity records by entry and entity ID
- Retrieve entity instance descriptions by entry and asym ID
- Look up chemical components, including DrugBank annotations, by component ID
- Describe pairwise polymeric interfaces by entry, assembly, and interface ID
- Aggregate entries or non-polymer entities into groups by deposition or component ID

## Use cases

### Structure Retrieval for Drug Discovery

Pull protein structure metadata directly from the canonical PDB archive when running computational drug discovery pipelines. GET `/core/entry/{entry_id}` returns the entry, and GET `/core/assembly/{entry_id}/{assembly_id}` returns the biological assembly detail. Suitable for research teams in pharma, biotech, and academic labs that need programmatic access to PDB entries.

Example prompt: Fetch the PDB entry '6VXX' via GET `/core/entry/{entry_id}` and its assembly 1 via GET `/core/assembly/{entry_id}/{assembly_id}` and return the title and resolution.

### Ligand and Chemical Component Lookups

Resolve chemical component identifiers to their full RCSB record including DrugBank annotations. GET `/core/chemcomp/{comp_id}` returns the chemical component definition, and GET `/core/drugbank/{comp_id}` returns DrugBank-derived annotations when available. Useful for cheminformatics workflows mapping ligands to drugs.

Example prompt: Look up CCD ID 'ATP' via GET `/core/chemcomp/{comp_id}` and return the chemical name, formula, and any DrugBank annotations from GET `/core/drugbank/{comp_id}.`

### Interface and Entity Analysis

Drive interface analysis pipelines by retrieving pairwise polymeric interfaces and the polymer entities they connect. GET `/core/interface/{entry_id}/{assembly_id}/{interface_id}` returns the interface description, while polymer entity endpoints provide entity-level metadata. Useful for structural biology teams studying protein-protein interactions.

Example prompt: Retrieve the interface description for entry '1A2K' assembly 1 interface 1, then fetch the polymer entities involved to summarise the interaction.

### Group-Based Aggregation Queries

Aggregate structures by deposition group or non-polymer entity group to study related entries together. GET `/core/entry_groups/{group_id}` returns entries by PDB Group Deposition ID, and GET `/core/nonpolymer_entity_groups/{group_id}` returns non-polymer entities grouped by chemical component. Useful for structural genomics consortia and curation teams.

Example prompt: Fetch the entry group for a PDB Group Deposition ID and produce a list of member entry IDs with their resolutions.

### Agent-Driven Structural Biology Tools via Jentic

AI agents that draft research summaries or feed structure data into modelling tools can call RCSB through Jentic without managing endpoint URLs by hand. The agent searches Jentic for the relevant intent, loads the schema, and executes entry, assembly, or chemical component lookups. The endpoints are public, so Jentic mediates discovery and parameter shaping.

Example prompt: Use Jentic to search 'get a pdb entry', load GET `/core/entry/{entry_id}`, and execute it with the entry ID supplied by the user.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/core/entry/{entry_id}` | Get a structure entry by entry ID |
| GET | `/core/assembly/{entry_id}/{assembly_id}` | Get a structural assembly by entry and assembly ID |
| GET | `/core/chemcomp/{comp_id}` | Get a chemical component by CCD ID |
| GET | `/core/drugbank/{comp_id}` | Get DrugBank annotations for a chemical component |
| GET | `/core/interface/{entry_id}/{assembly_id}/{interface_id}` | Get a pairwise polymeric interface description |
| GET | `/core/entry_groups/{group_id}` | Get an aggregated entry group |
| GET | `/core/branched_entity/{entry_id}/{entity_id}` | Get a branched entity by entry and entity ID |

## Key resources

- **Entries** — Retrieve PDB structure entries by entry ID
- **Assemblies** — Retrieve biological assemblies for an entry
- **Entities** — Retrieve polymer, non-polymer, and branched entities
- **Entity Instances** — Retrieve entity instances by entry and asym ID
- **Chemical Components** — Look up chemical components and DrugBank annotations
- **Interfaces** — Describe pairwise polymeric interfaces
- **Groups** — Aggregate entries and non-polymer entities into groups

## Why Jentic

- **Setup:** The RCSB RESTful API is unauthenticated, so wiring it by hand still leaves you building the base URL resolution, retry, and rate-limit plumbing for entry, entity, and chemical component reads yourself. Through Jentic you install once, import the RCSB RESTful API from the API Directory, and your agent calls it through a consistent execution layer.
- **Permission scoping:** RCSB puts the entry, assembly, and component ids in the URL path (`/core/entry/{entry_id}`, `/core/assembly/{entry_id}/{assembly_id}`), so a rule can pin your agent to specific entries or components. This API is read-only, so the agent can only retrieve the published records you allow it to.
- **Credential handling:** RCSB endpoints are unauthenticated, so there is no credential to store, and Jentic still routes every call through its own execution layer for consistent retry and logging. No token enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get a PDB entry' or 'look up a chemical component', and Jentic returns the matching RCSB operation with its input schema so the agent calls the right endpoint without parsing the RCSB reference.

## Related APIs

- **EBI Public Data APIs** — EBI provides sequence and pathway data; RCSB provides structural data - common to combine both in research pipelines.
- **NCBI Datasets API** — NCBI Datasets covers genome and gene records; RCSB covers protein structures associated with those genes.
- **ClinicalTrials.gov API** — ClinicalTrials.gov tracks human study records; RCSB hosts the underlying protein structures relevant to those studies.

## FAQ

### Why is there no official OpenAPI spec for the RCSB RESTful API?

RCSB publishes a Redoc-rendered API doc but not a structured OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the RCSB RESTful API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the RCSB RESTful API use?

The RCSB RESTful API is fully public and requires no authentication. Jentic still routes calls through its execution layer so agents benefit from consistent rate-limiting, retries, and logging across providers.

### Can I retrieve a PDB entry by ID with this API?

Yes. GET `/core/entry/{entry_id}` returns the structure record for the supplied PDB entry ID, and the related GET `/core/assembly/{entry_id}/{assembly_id}` endpoint returns the biological assembly detail.

### What are the rate limits for the RCSB RESTful API?

RCSB does not publish hard rate limits but advises avoiding sustained high-frequency requests against the public service. Apply client-side caching of entry records and exponential backoff on 429 or 503 responses for batch jobs.

### How do I look up a chemical component through Jentic?

Run pip install jentic, then search Jentic for 'look up a chemical component', load the GET `/core/chemcomp/{comp_id}` schema, and execute it with the CCD ID. Pair with GET `/core/drugbank/{comp_id}` for DrugBank annotations.

### Does the RCSB RESTful API support interface and entity instance lookups?

Yes. GET `/core/interface/{entry_id}/{assembly_id}/{interface_id}` returns pairwise polymeric interface descriptions and the entity-instance endpoints return descriptions keyed by entry ID and asym ID for polymer, non-polymer, and branched entities.

### Can I limit what my agent is allowed to do with the RCSB RESTful API?

Yes. Because you run Jentic One yourself, your own rules decide which RCSB operations and inputs the agent may call. This API is read-only, so an agent can at most retrieve published records, and since RCSB puts identifiers in the URL path (GET `/core/entry/{entry_id}`, GET `/core/assembly/{entry_id}/{assembly_id}`, GET `/core/chemcomp/{comp_id}`), you can pin the agent to specific entries, assemblies, or chemical components. Any operation you do not permit stays out of the agent's reach.