Tools

Seven tools spanning the structure-research arc — discover, fetch, find homologs, track ligands, compare, profile the corpus, and annotate — over experimental (PDB) and predicted (AlphaFold) structures from one surface:

protein_search_structures

Federated search across experimental (PDB) and predicted (computed-model) structures via RCSB Search v2.

• Free-text, protein-sequence (triggers an mmseqs2 similarity search), and organism / method / resolution filters
• content_type scopes the search to experimental, predicted, or all — the default all is a genuine union of both universes, so computed models appear alongside PDB entries
• Every hit names its source; experimental sequence hits expose a chainable PDB entry id plus the matched polymer entityId, with title, method, resolution, and organism enrichment, while computed models retain their complete model ID and parsed UniProt accession
• start and limit page through ranked results; nextStart is returned while another page remains
• Optional facets return a method / organism / release-year breakdown alongside the hits at no extra call, each reporting how many matches carry no value for that dimension; each dimension may be listed once
• Chain hit IDs straight into protein_get_structure

protein_get_structure

Fetch structures with metadata and coordinate-file URLs, resolving across providers by source.

• source: experimental takes PDB entry IDs, batched in one RCSB GraphQL call; it also resolves the computed-model IDs search returns (AF_* / MA_*), which come back as source: predicted credited to their modelling provider
• source: predicted takes UniProt accessions and returns the AlphaFold model with pLDDT/PAE confidence
• source: best_available takes UniProt accessions and returns the top federated model (experimental if one exists, else the best prediction)
• Per-ID partial success — unresolved IDs are listed in failed[], not a batch-level error
• include_coords inlines coordinate content; when a batch overflows the response budget it returns a per-structure size outline, so you can re-call with sections: [ids] for specific structures
• Every response carries an attribution block naming the upstream data licenses and citations (see Upstream data licensing)

protein_find_similar

Find structurally or evolutionarily related proteins, by sequence or by fold.

• by: sequence runs a synchronous RCSB mmseqs2 search; by: structure runs an asynchronous Foldseek search against experimental and predicted databases
• Query from a raw one-letter sequence, a PDB ID, or a UniProt accession
• Sequence searches accept start with limit and return nextStart while another page remains
• Foldseek targets default to pdb100 + afdb50; override via databases (e.g. afdb-swissprot, BFVD)
• Async jobs that exceed the poll budget return status: computing with a ticketId — re-call with ticket_id set to that value to poll the same job instead of resubmitting
• Each hit names the engine and source database it came from

protein_track_ligands

Ligand discovery and binding-site analysis across the PDB.

• mode: find_ligand resolves a name or formula to chemical component IDs with formula, weight, SMILES, and InChIKey
• mode: structures_with_ligand returns PDB entries containing a ligand by exact component ID
• mode: structures_with_ligand accepts start with limit and returns nextStart while another page remains
• mode: binding_site returns the protein residues lining a ligand's pocket in a structure, with contact distances
• Binding sites are experimental-only — computed from deposited coordinates (predicted models carry no bound ligands)

Paged RCSB results preserve the upstream order within each response. Resolution ties and changes in the live corpus mean traversal is best-effort across calls, not a stable export snapshot.

protein_compare_structures

Structural alignment of multiple structures (up to the configured PROTEIN_MAX_COMPARE_STRUCTURES cap) via the RCSB Structural Comparison service.

• Methods: tm-align, fatcat-rigid, fatcat-flexible
• reference: first aligns every structure to the first; reference: all_pairs computes the full pairwise matrix
• Optional per-structure chain restricts the alignment to a single chain
• A structure repeated in structures[] is compared once — the repeat would only add a self-alignment and a mirrored pair, which the resume mechanism cannot tell apart from the original
• Each pair is an independent async job, fanned out with a concurrency cap and per-pair partial success — a pair still computing when the budget elapses returns status: computing with its job uuid, and a failed pair degrades its row without sinking the others
• Re-call with a matching { a, b, uuid } entry in resume[] (copied from a prior response's pairs[]) to poll a computing pair's job instead of resubmitting
• Returns TM-score, RMSD, and aligned-residue count per pair, plus modeledResidues and coverage — each a [a, b] tuple, with coverage a 0–100 percentage of that structure's own modeled-residue count

protein_analyze_collection

Profile the PDB into distributions and trends over an optional scoping query — backed by RCSB's server-side facet engine (one call, compact buckets, no row pull).

• Group by method, organism, polymer_type, resolution, release_year, or molecular_weight
• One group_by dimension for a breakdown, or two distinct dimensions for a cross-tab (the first nests the second); a repeated dimension is rejected
• interval sets the bin width for value histograms or the period for date histograms (year / month / quarter)
• Scope with a free-text query, organism, method, or max_resolution; content_type selects the structure universe
• bucket_limit caps buckets per dimension level, not per response — a cross-tab applies it separately to the parent dimension and to the nested child inside each parent bucket, so up to bucket_limit × (1 + bucket_limit) buckets come back. Each level flags its own truncation, and bucketsReturned gives the realized total
• Every dimension reports missingValueCount — matches in scope carrying no value for that attribute, which therefore fall in no bucket (a resolution breakdown does not cover NMR entries, and neither method nor resolution covers computed models)