With the 3decision API, you can add annotations to your previously registered structures.
Annotations can be added to either a structure or a ligand.
Structure Annotations are accessible from the user interface in the "ANNOTATIONS" section of the Information Browser, where they are collected and organized in a table.
For each Structure Annotation, an ANNOTATION LABEL describes the annotation type (left column), and the corresponding ANNOTATION VALUE contains the information associated with the label (right column).
Ligand annotations can only be retreived from the API endpoint POST /annotations/ligands, they are not exposed in the UI.
This section describes in detail how to use the appropriate endpoints for Structure Annotations.
The main endpoints described in this page are:
- Add annotations:
POST /annotations - Edit annotations:
PUT /structures/{structure_id}/annotations - Delete annotations:
DELETE /annotations
The annotation values are searchable in 3decision from:
"Advanced Search" > Search "By Properties" > "Structure Entry Annotation"
¶ Add Structure Annotations
Structure Annotations can be added to a previously registered structure, in several steps:
- Retrieve the StructureID from the External Code
- Define the Annotation Label
- Add a Structure Annotation
¶ Structure Annotations input
All the details of the Annotations payload are described in the Schema of the POST /annotations endpoint request body. Briefly, the data required for every structure annotation is:
Label: corresponds to the “Annotation Value” that will be displayed in the right column of the Annotations table, in the UI.typeLabel: this is the annotation type that corresponds to the “Annotation Label” in the left column of the Annotations table, in the UI (to create a new typeLabel use thePOST /annotation-typesendpoint. See section below for step-by-step guide)targetID: the internal identifier of the structure you want to annotate (to retrieve the structureID from the external code, useGET /structures/code/{external_code}endpoint. See section below for step-by-step guide)targetType: type of target you want to annotate, either STRUCTURE (for protein annotations) or STR_SMALL_MOL (for ligand annotations)
¶ 1. Retrieve the StructureID from the External Code
The structureID is the unique identifier (in the format of a number) generated upon registration of any structure in the 3decision database. The external code is a 6-digit code that identifies a structure registered by a User in the user interface.
To retrieve the structureID from the external code, you can use the GET /structures/code/{external_code} endpoint.
¶ From the 3decision API interface:
- From the activated API interface, go to the
GET /structures/code/{external_code}endpoint - Click on "Try it out"
- Input the external code of the structure
- Click on “Execute”.
¶ Using the 'curl' command:
curl -X 'GET' \
'https://3decision-<customer>-api.discngine.cloud/structures/code/pjhzap' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJh********I6Y'
¶ Response example
{
"structures": [
{
"structure_id": 775841,
"external_code": "pjhzap"
}
]
}
The structureID is returned in the response body, and this is the value to use in the "targetID" field of the Annotations payload.
¶ 2. Define the Annotation Label
The Annotation Label is defined in the “typeLabel” field. You can either use an existing one (GET /annotations-types endpoint to get the full list), or create a new one (POST /annotation-types endpoint).
¶ Retrieve the existing Annotation Labels
¶ From the 3decision API interface:
- From the activated API interface, go to the
GET /annotations-typesendpoint - Click on "Try it out"
- Click on “Execute”.
¶ Using the 'curl' command:
curl -X 'GET' \
'https://3decision-<customer>-api.discngine.cloud/annotation-types' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJh********I6Y'
¶ Response example
In the Response Body, you get the full list of annotation types in your 3decision database.
If you want to use one, note the corresponding "annot_type_label" (the green text without brackets), to use in the input of the annotation, in the field "typeLabel".
¶ Create a New Annotation Label
¶ From the 3decision API interface:
- From the activated API interface, go to the
POST /annotation-typesendpoint - Click on "Try it out"
- In the Request body, write the label you want to assign to the annotation (in the example “DFG-1 residue”)
- Click on “Execute”.
¶ Using the 'curl' command:
curl -X 'POST' \
'https://3decision-<customer>-api.discngine.cloud/annotation-types' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJh********I6Y'
-H 'Content-Type: application/json' \
-d '{
"annot_type_label": "DFG-1 residue"
}'
¶ Response example
{
"annot_type_id": 12345
}
A new label type is created in 3decision. Use the name of the label (note: not the returned value, the label you gave in the input!), in the input of the annotation, in the field "typeLabel".
¶ 3. Add a Structure Annotation
The only Annotation that can be added to a Structure upon registration is the
Structure InternalID(only available typeLabel). Any other annotation must be added after registration, as documented in this section.
¶ From the 3decision API interface:
- From the activated API interface, go to the
POST /annotationsendpoint - Click on "Try it out"
- Copy and paste the annotation input in the "Request body", with at least the required fields. Here is an example you can use:
{
"label": "Val",
"typeLabel": "DFG-1 residue",
"targetId": 775841,
"targetType": "STRUCTURE"
}
- Click on "Execute"
¶ Using the 'curl' command:
curl -X 'POST' \
'https://3decision-<customer>-api.discngine.cloud/annotations' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********I6Y' \
-H 'Content-Type: application/json' \
-d '{
"label": "Val",
"typeLabel": "DFG-1 residue",
"targetId": 775841,
"targetType": "STRUCTURE"
}'
¶ Using Python
import json
import requests
def main():
api_token: str = "XXXXXXXXX"
api_url: str = "https://3decision-<customer>-api.discngine.cloud"
annotation_endpoint: str = f"{api_url}/annotations"
headers: dict[str, str] = {
"Authorization": f"Bearer {api_token}",
"Content-Type": "application/json",
"accept": "application/json",
"X-API-VERSION": "1",
}
annotation_payload = {
"label": "Val",
"typeLabel": "DFG-1 residue",
"targetId": 775841,
"targetType": "STRUCTURE"
}
body = str(json.dumps(annotation_payload)) # noqa: F821
# Call post annotation endpoint
requests.post(url=annotation_endpoint, headers=headers, data=body)
if __name__ == "__main__":
main()
¶ Response example
{
"id": 1234567
}
In the response body, you get an annotationID.
In the "ANNOTATIONS" section of the Information panel of your structure now you will find the new annotation
¶ Edit Structure Annotations
To edit a Structure Annotation (previously added to a structure), use the PUT /structures/{structure_id}/annotations endpoint.
To use this endpoint you need:
structureID: the internal identifier of the structure of which you want to edit the annotation (to retrieve the structureID, useGET /structures/code/{external_code}endpoint. See the dedicated section above for a step-by-step guide)annotationID: unique identifier of the annotation you want to edit (to retrieve the annotationID, useGET /structures/info/annotationendpoint. See section below for step-by-step guide)label: this is the new value of the annotation that will be shown in the right column of the Annotations table in the UItypeLabel: this is the annotation type that corresponds to the “Annotation Label” in the left column of the Annotations table in the UI
¶ 1. Retrieve the AnnotationID from the StructureID
The annotationID is the unique identifier (in the format of a number) generated upon registration of any structure annotation in 3decision.
The annotationID can be retrieved from the structureID, by using the GET /structures/info/annotation endpoint.
¶ From the 3decision API interface:
- From the activated API interface, go to the
GET /structures/info/annotationendpoint
- Click on "Try it out"
- Click on "Add number item"
- Input the structureID
- Click on “Execute”.
¶ Using the 'curl' command:
curl -X 'GET' \
'https://3decision-<customer>-api.discngine.cloud/structures/info/annotation?structure_id=775841' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJh********k3A'
¶ Response example
[
{
"ANNOTATION_INFO": {
"StructureAnnot": [
{
"ANNOT_TYPE_LABEL": "DFG-1 residue",
"ANNOT_VALUE": "Val",
"ANNOT_LINK": null,
"ANNOT_ID": 7289230
},
{
"ANNOT_TYPE_LABEL": "Internal ID",
"ANNOT_VALUE": "12345",
"ANNOT_LINK": null,
"ANNOT_ID": 7289229
},
{
"ANNOT_TYPE_LABEL": "Mutation",
"ANNOT_VALUE": "A319V",
"ANNOT_LINK": null,
"ANNOT_ID": 7289231
},
{
"ANNOT_TYPE_LABEL": "filename",
"ANNOT_VALUE": "6z2v.pdb",
"ANNOT_LINK": null,
"ANNOT_ID": 7289228
},
{
"ANNOT_TYPE_LABEL": "ligand warning",
"ANNOT_VALUE": "NonStandardWedgeConfiguration : 1 wedge bond with non-standard arrangement found (KHC)",
"ANNOT_LINK": null,
"ANNOT_ID": 7289227
}
]
},
"STRUCTURE_ID": 775841
}
]
The annotationID for every annotation associated with the structure of interest is returned in the response body. This is the value to use in the "annotationID" field of the endpoint PUT /structures/{structure_id}/annotations payload.
¶ 2. Edit a Structure Annotation
¶ From the 3decision API interface:
- From the activated API interface, go to the
PUT /structures/{structure_id}/annotationsendpoint - Click on "Try it out"
- Copy and paste the annotation input in the "Request body", with at least the required fields. Here is an example you can use:
{
"annotation_id": 7289230,
"label": "VALINE",
"type_label": "DFG-1 residue"
}
- Click on "Execute"
¶ Using the 'curl' command:
curl -X 'POST' \
'https://3decision-<customer>-api.discngine.cloud/annotations' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********I6Y' \
-H 'Content-Type: application/json' \
-d '{
"annotation_id": 7289230,
"label": "VALINE",
"type_label": "DFG-1 residue"
}'
¶ Response example
{
"annotation_id": 7289230,
"label": "VALINE",
"link": null,
"type_label": "DFG-1 residue"
}
In the "ANNOTATIONS" section of the Information panel of your structure now you will find the updated annotation
¶ Delete Structure Annotation
To delete a structure annotation, use the endpoint DELETE /annotations.
To use this endpoint you need the annotationID of the annotation you want to delete (to retrieve the annotationID, use GET /structures/info/annotation endpoint. See the dedicated section above for a step-by-step guide).
¶ From the 3decision API interface:
- From the activated API interface, go to the
DELETE /annotationsendpoint - Click on "Try it out"
- Copy and paste the annotationID in the "Request body". Here is an example:
{
"id": 7289231,
}
- Click on "Execute"
¶ Using the 'curl' command:
curl -X 'POST' \
'https://3decision-<customer>-api.discngine.cloud/annotations' \
-H 'accept: */*' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********I6Y' \
-H 'Content-Type: application/json' \
-d '{
"id": 7289231
}'
¶ Response
The annotation is deleted from the database and is not listed in the "ANNOTATIONS" section of the Information panel of your structure anymore.