molecules-public

Update Molecule Metadata

Update a molecule. All fields are optional and applied together; null clears a field.

Merge your own annotations with properties (tool scores aren't editable here). Set the derived-from molecule with source, this group's primary structure file with fileId, and the per-group display name with name.

A name already used in the group returns 409.

patch/api/molecules/{molecule_id}/metadata

Request

  • Base URL: https://app.tamarind.bio
  • URL: https://app.tamarind.bio/api/molecules/{molecule_id}/metadata
  • Auth: API key in header x-api-key

Path parameters

molecule_idstring required

Request body

propertiesobject nullable
sourcestring nullable
fileIdstring nullable
namestring nullable
metadataobject nullable

DEPRECATED alias for properties, kept for callers written against the original v1 shape. Send properties instead; if both are sent, properties wins.

Response

Successful Response

idstring required
namestring nullable required
typestring nullable required
entityobject required

The molecule's chains: chain id -> the chain's sequence — amino acids for a protein, nucleotides for a nucleic acid, or a SMILES string for a small molecule. chainMapping[<chain id>].type says which.

chainMappingobject required

Per-chain detail, keyed by the same chain ids as entity: its type and any tags.

filesobject required

Structures and other artifacts, keyed by the PRODUCER that made them — a tool name (alphafold, protenix) or user for your own uploads. Each entry carries a short-lived signed downloadUrl. This is where hasStructure: true resolves to an actual file. It can be EMPTY on the org-wide listing even for a molecule that has a structure: with no group to relabel a chain-bearing file's chains against, those files are served without a link and dropped — pass group, or read the molecule by id.

metadataobject required

TWO namespaces in one map, and knowing which is which is what makes filter work.

A key naming a TOOL holds a LIST of that tool's score runs — {"protenix": [{"jobId": "...", "runId": "...", "ipSAE_AB": 0.62}]}. Any other key is a SCALAR annotation you set yourself — {"affinity_nM": 12.4}.

One carve-out: a key naming a COMPUTED schema field holds that formula's value, evaluated on read and never stored. It is READ-ONLY — you cannot set it here — and filter/sortBy do not address it, because they resolve against stored values and a computed field has none.

Filter and sort address the two writable namespaces differently: a tool score is the DOTTED path protenix.ipSAE_AB (?filter=protenix.ipSAE_AB:gte:0.5), and a scalar is the BARE key (?filter=affinity_nM:lte:50). Metric names are case-sensitive and must match what you see here. exists applies to scalar keys only; to ask whether a tool reported a metric, filter on its value instead.

Each run entry carries jobId AND runId, which answer different questions. jobId is the DISPATCH that produced the entry, and the engine dispatches one job per molecule — so the same run has a different jobId on every molecule and grouping a page by it yields one group per molecule. runId is the run — the pipeline NODE RUN, where there is one — and is the field to group by. Pass it straight back as nodeRunId to list everything that node run produced; the nr- prefix a pipeline run carries is accepted as-is, and nodeRuns[].id (the bare uuid) names the same run.

truncatedstring[] required

Which inline collections were CAPPED for this molecule, so you know you are not looking at all of it: "scores" (more score runs than returned), "files", or "groups" (page the rest via GET /molecules/{moleculeId}/groups). Empty means the maps above are the molecule's full accumulated history.

createdAtstring nullable required
addedAtstring nullable required
createdBystring nullable required
sourcestring nullable required
tagsstring[] required
notesstring nullable required
hasStructureboolean required

Whether this molecule has a structure at all (a pdb/cif, or an sdf). The files themselves are in files, keyed by the tool that produced them — but see that field: on the org-wide listing files can be empty even when this is true, because chain-bearing files need a group to relabel against. Pass group, or read the molecule by id, to get the download.

matchedOnstring[] nullable required

Changes

No recorded changes to this operation across all 1 revision of this API.