/rcsb/polymer-entities

POST /api/rcsb/polymer-entities

Price: 5 credits

Get one polymer entity of a PDB structure — its sequence, source organism and annotations

How to use it

A polymer entity is one distinct chain sequence of a structure, not one chain copy: a homodimer has one entity with two `author_chain_ids`. Address it as `4HHB_1` or as the entry id plus `entity_id`, both case-insensitive; the entry endpoint lists the entity numbers a structure has. `uniprot_ids` and `alignments` are the mapping to reference sequences and are absent for DNA, RNA and synthetic constructs, which have no UniProt counterpart.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• polymer_entity string required — Polymer entity identifier such as 4HHB_1, or the PDB entry id when entity_id is given (examples: "4HHB_1", "4HHB"; minLength: 1)
• entity_id string nullable — Entity number inside the entry, required when polymer_entity carries only the entry id (examples: "1"; minLength: 1)

Response

• @type string (default: "RcsbPolymerEntity")
• id string (default: "")
• entry_id string (default: "")
• entity_id string (default: "")
• description string (default: "")
• common_names array (default: [])
• macromolecular_names array (default: [])
• polymer_names array (default: [])
• polymer_type string (default: "")
• entity_polymer_type string (default: "")
• sequence string (default: "")
• canonical_sequence string (default: "")
• sequence_length integer nullable
• formula_weight number nullable
• molecule_count integer nullable
• source_method string (default: "")
• has_multiple_sources boolean nullable
• source_part_count integer nullable
• source_taxonomy_count integer nullable
• details string (default: "")
• fragment string (default: "")
• mutation string (default: "")
• ec_numbers array (default: [])
• ec_lineage array (default: [])
  • @type string (default: "RcsbLineageNode")
  • id string (default: "")
  • name string (default: "")
  • depth integer nullable
• enzyme_classes array (default: [])
• chain_ids array (default: [])
• author_chain_ids array (default: [])
• strand_ids string (default: "")
• uniprot_ids array (default: [])
• target_identifier string (default: "")
• membrane_lineage array (default: [])
  • @type string (default: "RcsbLineageNode")
  • id string (default: "")
  • name string (default: "")
  • depth integer nullable
• membrane_lineage_provenance_code string (default: "")
• monomer_count integer nullable
• nonstandard_monomers array (default: [])
• nonstandard_monomer_count integer nullable
• mutation_count integer nullable
• conflict_count integer nullable
• deletion_count integer nullable
• insertion_count integer nullable
• artifact_monomer_count integer nullable
• has_nonstandard_linkage boolean nullable
• has_nonstandard_monomer boolean nullable
• source_organisms array (default: [])
  • @type string (default: "RcsbOrganism")
  • scientific_name string (default: "")
  • common_name string (default: "")
  • common_names array (default: [])
  • parent_scientific_name string (default: "")
  • tax_id string (default: "")
  • source_type string (default: "")
  • gene_names array (default: [])
  • provenance_source string (default: "")
  • begin_sequence_position integer nullable
  • end_sequence_position integer nullable
  • lineage array (default: [])
    • @type string (default: "RcsbLineageNode")
    • id string (default: "")
    • name string (default: "")
    • depth integer nullable
• host_organisms array (default: [])
  • @type string (default: "RcsbOrganism")
  • scientific_name string (default: "")
  • common_name string (default: "")
  • common_names array (default: [])
  • parent_scientific_name string (default: "")
  • tax_id string (default: "")
  • source_type string (default: "")
  • gene_names array (default: [])
  • provenance_source string (default: "")
  • begin_sequence_position integer nullable
  • end_sequence_position integer nullable
  • lineage array (default: [])
    • @type string (default: "RcsbLineageNode")
    • id string (default: "")
    • name string (default: "")
    • depth integer nullable
• expression_systems array (default: [])
  • @type string (default: "RcsbExpressionSystem")
  • gene_source_scientific_name string (default: "")
  • gene_source_common_name string (default: "")
  • gene_source_tax_id string (default: "")
  • gene_names string (default: "")
  • host_organism_scientific_name string (default: "")
  • host_organism_tax_id string (default: "")
  • host_vector_type string (default: "")
  • plasmid_name string (default: "")
  • description string (default: "")
  • sequence_type string (default: "")
  • source_variant string (default: "")
  • gene_source_genus string (default: "")
  • gene_source_organ string (default: "")
  • gene_source_tissue string (default: "")
  • gene_source_cell string (default: "")
  • gene_source_cell_line string (default: "")
  • host_organism_common_name string (default: "")
  • host_organism_genus string (default: "")
  • host_organism_species string (default: "")
  • host_organism_strain string (default: "")
  • begin_sequence_position integer nullable
  • end_sequence_position integer nullable
  • gene_source_species string (default: "")
  • gene_source_strain string (default: "")
  • gene_source_variant string (default: "")
  • gene_source_atcc string (default: "")
  • gene_source_cellular_location string (default: "")
  • host_organism_details string (default: "")
  • host_organism_cell_line string (default: "")
  • host_organism_cellular_location string (default: "")
  • host_organism_organ string (default: "")
  • host_organism_tissue string (default: "")
  • host_vector_name string (default: "")
  • plasmid_details string (default: "")
  • details string (default: "")
• alignments array (default: [])
  • @type string (default: "RcsbSequenceAlignment")
  • reference_database_name string (default: "")
  • reference_database_accession string (default: "")
  • provenance_source string (default: "")
  • entity_sequence_coverage number nullable
  • reference_sequence_coverage number nullable
  • aligned_regions array (default: [])
    • @type string (default: "RcsbAlignedRegion")
    • entity_begin_sequence_position integer nullable
    • reference_begin_sequence_position integer nullable
    • length integer nullable
• annotations array (default: [])
  • @type string (default: "RcsbAnnotation")
  • id string (default: "")
  • name string (default: "")
  • type string (default: "")
  • description string (default: "")
  • provenance_source string (default: "")
  • assignment_version string (default: "")
  • lineage array (default: [])
    • @type string (default: "RcsbLineageNode")
    • id string (default: "")
    • name string (default: "")
    • depth integer nullable
  • additional_properties array (default: [])
    • @type string (default: "RcsbNamedValues")
    • name string (default: "")
    • values array (default: [])
• features array (default: [])
  • @type string (default: "RcsbEntityFeature")
  • id string (default: "")
  • name string (default: "")
  • type string (default: "")
  • provenance_source string (default: "")
  • assignment_version string (default: "")
  • position_count integer nullable
  • values array (default: [])
  • additional_properties array (default: [])
    • @type string (default: "RcsbNamedValues")
    • name string (default: "")
    • values array (default: [])
• feature_summaries array (default: [])
  • @type string (default: "RcsbFeatureSummary")
  • type string (default: "")
  • count integer nullable
  • coverage number nullable
  • minimum_length integer nullable
  • maximum_length integer nullable
• group_memberships array (default: [])
  • @type string (default: "RcsbGroupMembership")
  • group_id string (default: "")
  • aggregation_method string (default: "")
  • similarity_cutoff number nullable
  • aligned_regions array (default: [])
    • @type string (default: "RcsbAlignedRegion")
    • entity_begin_sequence_position integer nullable
    • reference_begin_sequence_position integer nullable
    • length integer nullable
• target_references array (default: [])
  • @type string (default: "RcsbTargetReference")
  • resource_name string (default: "")
  • resource_version string (default: "")
  • target_id string (default: "")
  • target_tax_id string (default: "")
  • aligned_regions array (default: [])
    • @type string (default: "RcsbAlignedRegion")
    • entity_begin_sequence_position integer nullable
    • reference_begin_sequence_position integer nullable
    • length integer nullable
• target_cofactors array (default: [])
  • @type string (default: "RcsbTargetCofactor")
  • name string (default: "")
  • chem_comp_id string (default: "")
  • smiles string (default: "")
  • inchi_key string (default: "")
  • mechanism_of_action string (default: "")
  • binding_assay_type string (default: "")
  • binding_assay_value number nullable
  • resource_name string (default: "")
  • resource_version string (default: "")
  • resource_id string (default: "")
  • target_resource_id string (default: "")
  • pubmed_ids array (default: [])
  • patent_numbers array (default: [])
  • is_neighbor boolean nullable
  • prd_id string (default: "")
• keywords string (default: "")
• systematic_names array (default: [])
• prd_id string (default: "")
• chemical_reference_definition_id string (default: "")

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — Polymer entity not found Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.