Annotation API

Annotation¶

Add an annotation comment¶

Parameter /annotation/comment/:file/:annotation¶

Name	Type	Description
file	String	File id
annotation	String	Annotation id

POST /annotation/comment/:file/:annotation¶

Name	Type	Description
message	String	Annotation comment message

Example usage:

curl -X POST -H 'Authorization: Bearer <auth_token>' -F "message=my message" 'https://smartshape.io/annotation/comment/619379e595dff80f314dcbdd/6193898cb20dae117640910e'

Success-Response:

HTTP/1.1 200 OK
{
    "success":true,
    "data":{
        "message": "Candice who?",
        "uuid": "dac88599-9f9f-40de-a2b7-e3ce3433cad8",
        "date": 1637063371892,
        "file": "619379e595dff80f314dcbdd",
        "annotation": "6193898cb20dae117640910e",
        "author": {
            "id": "619379e595dff80f314dcbdd",
            "username": "test"
        },
        "readBy":[],
        "id": "61939acbb20dae1176409fd3"
    }
}

Success 200¶

Name	Type	Description
success	Bool
data	Object	Annotation comment information
data.id	String	Annotation comment id
data.file	String	File id
data.annotation	String	Annotation id
data.message	String	Annotation comment message
data.date	Number	Date the message was sent
data.author	String	Information about the author
data.readBy	[String]	Email list of people who read the message

Add or update annotation attributes¶

Parameter /annotation/attributes/:file¶

Name	Type	Description
file	String	File id

POST /annotation/attributes/:file¶

Name	Type	Description
JSON	json	object describing the attributes to add or update

Example usage:

curl -X POST -H 'https://smartshape.io/annotation/attributes/5dde5b7b94c75819fd42867a' \
    'Authorization: Bearer <auth_token>' \
    -H 'Content-Type: application/json' \
    -d '{
            "attributes": {
                "5964f9e0435711191f0f9132": { "material": "metal", "color": "blue" }
            }
        }'

Success-Response:

HTTP/1.1 200 OK
[
    {
        "cameraX": 38.434475,
        "cameraY": 68.973259,
        "cameraZ": 48.012657,
        "cameraTargetX": 0.000005,
        "cameraTargetY": 5.000007,
        "cameraTargetZ": 0.000015,
        "name": "test",
        "content": "",
        "type": 0,
        "date": 1574859257842,
        "lastUpdate": 1574859257842,
        "file": "5dde5b7b94c75819fd42867a",
        "author": "test@smartshape.io",
        "permissions": {
            "_id": "5dde71f9e310a40615cb08bc",
            "writeUuid": [],
            "readUuid": [],
            "writeFolders": [],
            "readFolders": []
            "writeTargets": [],
            "readTargets": [],
            "delete": [],
            "writeTitle": [],
            "readTitle": [],
            "writeDiscussion": [],
            "readDiscussion": [],
            "writeDescription": [],
            "readDescription": [],
        },
        "writePermissions": [],
        "readPermissions": [],
        "folders": [],
        "tags": [],
        "targetObjects": [],
        "targets": [
            {
                "node": "5dde5b7cde0f261b9b18ea1c",
                "position": {
                    "x": 23.38378,
                    "y": 10,
                    "z": -8.37059
                },
                "surfaceNormal": {
                    "x": 1,
                    "y": 0,
                    "z": 0
                },
                "_id": "5dde71f9e310a40615cb08be"
            }
        ],
        "uuid": "7dce0bd9-6ede-4e4f-b73c-3409e5bbf95f",
        "attributes": {
            "color": {
                "key": "color",
                "value": "red",
                "origin": "imported"
            },
            "material": {
                "key": "material",
                "value": "metal",
                "origin": "imported"
            }
        },
        "id": "5964f9e0435711191f0f9132"
    }
]

Success 200¶

Name	Type	Description
result	String	JSON object of the updated nodes

Create an annotation¶

Parameter /annotation/create/:file¶

Name	Type	Description
file	String	File id

POST /annotation/create/:file¶

Name	Type	Description
name	String	Annotation name
content	String	Annotation content
cameraTargetX	Number	Camera target X position of the annotation
cameraTargetY	Number	Camera target Y position of the annotation
cameraTargetZ	Number	Camera target Z position of the annotation
cameraX	Number	Camera X position of the annotation
cameraY	Number	Camera Y position of the annotation
cameraZ	Number	Camera Z position of the annotation
targets	Array	List of annotation targets
targetObjects	Array	List of annotation target objects
permissions	Object	Permissions of individual fields of the annotation
permissions.writeUuid	[String]	Permission to modify field `uuid` of the annotation
permissions.readUuid	[String]	Permission to read field `uuid` of the annotation
permissions.writeFolders	[String]	Permission to modify field `folders` of the annotation
permissions.readFolders	[String]	Permission to read field `folders` of the annotation
permissions.writeTargets	[String]	Permission to modify field `targets` of the annotation
permissions.readTargets	[String]	Permission to read field `targets` of the annotation
permissions.delete	[String]	Permission to delete the annotation
permissions.writeTitle	[String]	Permission to modify field `name` of the annotation
permissions.readTitle	[String]	Permission to read field `name` of the annotation
permissions.writeDiscussion	[String]	Permission to modify annotation comments
permissions.readDiscussion	[String]	Permission to read annotation comments
permissions.writeDescription	[String]	Permission to modify field `content` of the annotation
permissions.readDescription	[String]	Permission to read field `content` of the annotation
writePermissions	Array	Permissions required to modify the annotation
readPermissions	Array	Permissions required to read the annotation
folders	[String]	optional Folders this annotation belongs to

Example usage:

curl -X POST \
    https://smartshape.io/annotation/create/5bb60111e75d6d0fd21fe239 \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "test",
        "cameraX": 45.00554,
        "cameraY": 25.04689,
        "cameraZ": 63.514038,
        "cameraTargetX": 5.00554,
        "cameraTargetY": 5.04689,
        "cameraTargetZ": 3.514038,
        "targets": [
            {
                "node": "5bc09d1c3fd9f525f390e937",
                "position": {
                    "x": 1.884846,
                    "y": -0.41996,
                    "z": -0.215639
                },
                "surfaceNormal": {
                    "x": 1,
                    "y": 0,
                    "z": 0
                }
            }
        ],
        "targetObjects": [
            {
                "node": "5bc09d1c3fd9f5254567e937",
                "position": {
                    "x": 12.884846,
                    "y": -50.215639,
                    "z": -30.41996
                }
            }
        ]
    }'

Success-Response:

HTTP/1.1 200 OK
{
    "success": true,
    "data": {
        "name": "test",
        "cameraX": 45.00554,
        "cameraY": 25.04689,
        "cameraZ": 63.514038,
        "cameraTargetX": 5.00554,
        "cameraTargetY": 5.04689,
        "cameraTargetZ": 3.514038,
        "date": 1539354715414,
        "lastUpdate": 1539354715414,
        "file": "5bb60111e75d6d0fd21fe239",
        "author": "test@smartshape.io",
        "permissions": {
            "_id": "61a7a26b9e90ee10f4f349cf",
            "writeUuid": [],
            "readUuid": [],
            "writeFolders": [],
            "readFolders": [],
            "writeTargets": [],
            "readTargets": [],
            "delete": [],
            "writeTitle": [],
            "readTitle": [],
            "writeDiscussion": [],
            "readDiscussion": [],
            "writeDescription": [],
            "readDescription": []
        },
        "writePermissions": [],
        "readPermissions": [],
        "folders": [],
        "tags": [],
        "targetObjects": [
            {
                "node": "5bc09d1c3fd9f5254567e937",
                "position": {
                    "x": 12.884846,
                    "y": -50.215639,
                    "z": -30.41996
                },
                "_id": "61a7a26b9e90ee10f4f349d1",
                "id": "61a7a26b9e90ee10f4f349d1"
            }
        ],
        "targets": [
            {
                "node": "5bc09d1c3fd9f525f390e937",
                "position": {
                    "x": 1.884846,
                    "y": -0.41996,
                    "z": -0.215639
                },
                "surfaceNormal": {
                    "x": 1,
                    "y": 0,
                    "z": 0
                },
                "_id": "61a7a26b9e90ee10f4f349d2",
                "id": "61a7a26b9e90ee10f4f349d2"
            }
        ],
        "uuid": "34757fe8-c0c8-404f-b6d3-2d5de9e26158",
        "attributes": {},
        "id": "5bc0b05b50fa6c26a9610f24"
    }
}

Success 200¶

Name	Type	Description
success	Bool
data	Array	Annotation list

POST /annotation/search/form/¶

Name	Type	Description
name	Object	Name of the search form
files	[String]	optional IDs of the files to restrict this search form to
searchQuery	String	Template of search query generated by the search form. The query can contain variables like `$name` that will be replaced by what the user put in the field named `name`
description	Object	optional Description of the search form
fields	[Object]	optional Fields of the search form
fields.type	String	Determines the type of field shown in the UI. Possible values: - textinput: Shows a text area which allows the user to enter any string - select: Shows a drop down menu which lets the user choose among the values of the `fields.data` field - number: Shows a number selector which lets the user to enter a valid number - switch: Shows a switch which allows the user to enable or disable it
fields.data	[String]	optional Values showed in the drop down menu when the type is `select`
fields.label	String	Label shown next to the field in the UI
readPermissions	[String]	optional Permissions required to read this search form

Example usage:

curl -X POST \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'Content-Type: application/json' \
    'https://smartshape.io/annotation/search/form/' \
    -d '
    {
        "name": {
            "en_US": "Search annotations by tag",
            "fr_FR": "Rechercher des annotations par tag"
        },
        "searchQuery": "($tag1 and tag:\"Tag 1\") or ($tag2 and tag:\"Tag 2\")",
        "description": {
            "en_US": "Search for annotations that feature at least one of the selected tags.",
            "fr_FR": "Rechercher les annotations qui présentent au moins un des tags sélectionnés."
        },
        "fields": [
            {
                "type": "switch",
                "name": "tag1",
                "label": "Tag 1"
            },
            {
                "type": "switch",
                "name": "tag2",
                "label": "Tag 2"
            }
        ],
        "readPermissions": [],
        "files": []
    }'

Success-Response:

HTTP/1.1 200 OK
{
    "name": {
        "fr_FR": "Rechercher des annotations par tag",
        "en_US": "Search annotations by tag"
    },
    "searchQuery": "($tag1 and tag:\"Tag 1\") or ($tag2 and tag:\"Tag 2\")",
    "description": {
        "fr_FR": "Rechercher les annotations qui présentent au moins un des tags sélectionnés.",
        "en_US": "Search for annotations that feature at least one of the selected tags."
    },
    "readPermissions": [],
    "fields": [
        {
            "type": "switch",
            "name": "tag1",
            "label": "Tag 1",
            "_id": "5c4ae373c97a4b690dd4caa9"
        },
        {
            "type": "switch",
            "name": "tag2",
            "label": "Tag 2",
            "_id": "5c4ae373c97a4b690dd4caa8"
        }
    ],
    "files": [],
    "id": "5c4ae373c97a4b690dd4caa7"
}

Success 200¶

Name	Type	Description
result	json	JSON object of the created annotation search forms

Delete an annotation¶

Parameter /annotation/delete/:file/:annotation¶

Name	Type	Description
file	String	File id
annotation	String	Annotation id

Example usage:

curl -X DELETE -H 'Authorization: Bearer <auth_token>' https://smartshape.io/annotation/delete/58d3aa7c0868c419e48af374/58d3d42cd08d7c1987feb3bd"

Success-Response:

HTTP/1.1 200 OK
{
    "success":true
}

Success 200¶

Name	Type	Description
success	Bool

Parameter /annotation/search/form/:searchform¶

Name	Type	Description
searchform	String	Annotation search form id

Example usage:

curl -X DELETE \
    -H 'Authorization: Bearer <auth_token>' \
    'https://smartshape.io/annotation/search/form/5fff02ed87d3c866709c16a4'

Success-Response:

 HTTP/1.1 200 OK
"5c4ae40dc97a4b690dd4caad"

Success 200¶

Name	Type	Description
ID	String	of the deleted search form

List annotation comments¶

Parameter /annotation/comment/:file/:annotation¶

Name	Type	Description
file	String	File id
annotation	String	Annotation id

Example usage:

curl -X GET -H 'Authorization: Bearer <auth_token>' 'https://smartshape.io/annotation/comment/619379e595dff80f314dcbdd/6193898cb20dae117640910e'

Success-Response:

HTTP/1.1 200 OK
{
    "success":true,
    "data":[
        {
            "message":"Knock knock",
            "uuid": "34e20537-0be3-4aac-a563-23787eeb6aeb",
            "date":1637059017477,
            "file":"619379e595dff80f314dcbdd",
            "annotation":"6193898cb20dae117640910e",
            "author": {
                "id": "619379e595dff80f314dcbdd",
                "username": "test"
            },
            "readBy":[
                "619379e595dff80f314dcbdd"
            ],
            "id":"619389c9b20dae117640913a",
            "mine":true
        },
        {
            "message":"Who's there?",
            "uuid": "be1ee483-5c7b-4e18-b53a-53546a1664bf",
            "date":1637059023959,
            "file":"619379e595dff80f314dcbdd",
            "annotation":"6193898cb20dae117640910e",
            "author": {
                "id": "6193898cb20dae117640910e",
                "username": "test"
            },
            "readBy":[
                "619379e595dff80f314dcbdd"
            ],
            "id":"619389cfb20dae1176409141",
            "mine":false
        },
        {
            "message":"Candice",
            "uuid": "5e1ea493-6b0d-6f13-c43e-52819b1764hs",
            "date":1637059029057,
            "file":"619379e595dff80f314dcbdd",
            "annotation":"6193898cb20dae117640910e",
            "author": {
                "id": "619379e595dff80f314dcbdd",
                "username": "test"
            },
            "readBy":[
            ],
            "id":"619389c4b20dae1176409157",
            "mine":true
        }
    ]
}

Success 200¶

Name	Type	Description
success	Bool
data	Array	Annotation comments list

List annotation search forms¶

Parameter /annotation/search/form/:file¶

Name	Type	Description
file	String	optional File id

Example usage:

curl -X GET \
    -H 'Authorization: Bearer <auth_token>' \
    'https://smartshape.io/annotation/search/form/5fff02ed87d3c866709c16a4'

Success-Response:

HTTP/1.1 200 OK
[
    {
        "name": {
            "en_US": "Search annotations by tag",
            "fr_FR": "Rechercher des annotations par tag"
        },
        "searchQuery": "($tag1 and tag:\"Tag 1\") or ($tag2 and tag:\"Tag 2\")",
        "description": {
            "en_US": "Search for annotations that feature at least one of the selected tags.",
            "fr_FR": "Rechercher les annotations qui présentent au moins un des tags sélectionnés."
        },
        "readPermissions": [],
        "fields": [
            {
                "type": "switch",
                "name": "tag1",
                "label": "Tag 1",
                "_id": "5c4ae373c97a4b690dd4caa9"
            },
            {
                "type": "switch",
                "name": "tag2",
                "label": "Tag 2",
                "_id": "5c4ae373c97a4b690dd4caa8"
            }
        ],
        "files": [],
        "id": "5c4ae373c97a4b690dd4caa7"
    }
]

List annotations¶

Parameter /annotation/list/:file¶

Name	Type	Description
file	String	File id

GET /annotation/list/:file¶

Name	Type	Description
exclude	String	optional Comma separated list of fields to exclude from the result (examples of fields: 'name', 'unreadComments')
format	String	optional Format to export the results in. Formats available: - bcf - csv - json - xlsx - xml

Example usage:

curl -X GET -H 'Authorization: Bearer <auth_token>' 'https://smartshape.io/annotation/list/619379e595dff80f314dcbdd'

Example usage: Exclude the unreadComments property.

curl -X GET -H 'Authorization: Bearer <auth_token>' 'https://smartshape.io/annotation/list/619379e595dff80f314dcbdd?exclude=unreadComments'

Example usage: Export the results as XLSX file.

curl -X GET -H 'Authorization: Bearer <auth_token>' 'https://smartshape.io/annotation/list/619379e595dff80f314dcbdd?format=xlsx'

Success-Response:

HTTP/1.1 200 OK
{
    "success":true,
    "data": [
        {
            "cameraX": 23.963634,
            "cameraY": 9.001619,
            "cameraZ": 11.441383,
            "cameraTargetX": -1.194216,
            "cameraTargetY": -0.311804,
            "cameraTargetZ": 4.561752,
            "name": "Door",
            "content": "This is the main entrance door.",
            "type": 0,
            "uuid": "90acf5e7-f990-454a-8f41-eb8707d4ecb0",
            "date": 1637058956046,
            "lastUpdate": 1637058956046,
            "file": "619379e595dff80f314dcbdd",
            "author": "test@smartshape.io",
            "permissions": {
                "_id": "6193898cb20dae117640910d",
                "writeUuid": [],
                "readUuid": [],
                "writeFolders": [],
                "readFolders": [],
                "writeTargets": [],
                "readTargets": [],
                "delete": [],
                "writeTitle": [],
                "readTitle": [],
                "writeDiscussion": [],
                "readDiscussion": [],
                "writeDescription": [],
                "readDescription": []
            },
            "writePermissions": [],
            "readPermissions": [],
            "folders": [],
            "tags": [],
            "targetObjects": [],
            "targets": [
                {
                    "node": "61937a3cd22f281386815fcd",
                    "position": {
                        "x": -0.099363,
                        "y": -0.556553,
                        "z": 5.288486
                    },
                    "surfaceNormal": {
                        "x": 1,
                        "y": 0,
                        "z": 0
                    }
                    "_id": "6193898cb20dae117640910f",
                    "id": "6193898cb20dae117640910f",
                    "subsurfaceId": 149,
                    "surfaceUuid": "1d7b7560-2bf3-2df1-27e4-4c8f7f3e3716",
                    "nodeName": ""
                }
            ],
            "attributes": {},
            "id": "6193898cb20dae117640910e",
            "unreadComments": 0
            "attributeMetadata": [],
            "color": [
                4,
                10
            ],
            "shape": 3
        },
        {
            "cameraX": 19.02058,
            "cameraY": 15.794342,
            "cameraZ": 16.0175,
            "cameraTargetX": 2.599203,
            "cameraTargetY": -0.06352,
            "cameraTargetZ": 0.337793,
            "name": "Window",
            "content": "This is the first floor window.",
            "type": 0,
            "uuid": "ce9051b4-3b96-476e-af65-089e3cd32eb7"
            "date": 1637059097258,
            "lastUpdate": 1637059097258,
            "file": "619379e595dff80f314dcbdd",
            "author": "test@smartshape.io",
            "permissions": {
                "_id": "61938a19b20dae117640916a",
                "writeUuid": [],
                "readUuid": [],
                "writeFolders": [],
                "readFolders": [],
                "writeTargets": [],
                "readTargets": [],
                "delete": [],
                "writeTitle": [],
                "readTitle": [],
                "writeDiscussion": [],
                "readDiscussion": [],
                "writeDescription": [],
                "readDescription": []
            },
            "writePermissions": [],
            "readPermissions": [],
            "folders": [],
            "tags": [],
            "targetObjects": [],
            "targets": [
                {
                    "node": "61937a3dd22f28138681732d",
                    "position": {
                        "x": 3.821942,
                        "y": 6.396293,
                        "z": 4.446007
                    },
                    "surfaceNormal": {
                        "x": -1.87233,
                        "y": 5.841121,
                        "z": -0.011727
                    },
                    "_id": "61938a19b20dae117640916c",
                    "id": "61938a19b20dae117640916c",
                    "subsurfaceId": 0,
                    "surfaceUuid": "2811f73a-36c9-6129-7fdf-4d1130e43360",
                    "nodeName": ""
                }
            ],
            "attributes": [],
            "id": "61938a19b20dae117640916b",
            "unreadComments": 0,
            "attributeMetadata": [],
            "label": "Window is attached to an object made of undefined"
        }
    ]
}

Success 200¶

Name	Type	Description
success	Bool
data	Array	Annotation list

Search for annotations¶

Parameter /annotation/search/:file¶

Name	Type	Description
file	String	File id

POST /annotation/search/:file¶

Name	Type	Description
queries	[String]	Search queries.

Example usage:

curl -X POST https://smartshape.io/annotation/search/5b27b1c6325485158e1da61f \
   -H 'Authorization: Bearer <auth_token>' \
   -H 'Content-Type: application/json' \
   -d '{
         "queries": [
             "title:\"test*\" and #monday"
         ]
       }'

Success-Response:

HTTP/1.1 200 OK
{
    "data": {
        "title:\"test*\" and #monday": {
            "annotations": [
                {
                    "cameraTargetX": 0.151819,
                    "cameraTargetY": 0.47007,
                    "cameraTargetZ": -0.274362,
                    "cameraX": 1.880337,
                    "cameraY": 1.763491,
                    "cameraZ": 2.026447,
                    "name": "Test",
                    "content": "",
                    "type": 0,
                    "date": 1531298793641,
                    "lastUpdate": 1531298793641,
                    "file": "5b27b1c6325485158e1da61f",
                    "author": "test@smartshape.io",
                    "permissions": {
                        "_id": "6193898cb20dae117640910d",
                        "writeUuid": [],
                        "readUuid": [],
                        "writeFolders": [],
                        "readFolders": [],
                        "writeTargets": [],
                        "readTargets": [],
                        "delete": [],
                        "writeTitle": [],
                        "readTitle": [],
                        "writeDiscussion": [],
                        "readDiscussion": [],
                        "writeDescription": [],
                        "readDescription": []
                    },
                    "writePermissions": [],
                    "readPermissions": [],
                    "folders": [],
                    "tags": [
                        "tag3",
                        "monday"
                    ],
                    "targetObjects": [],
                    "targets": [
                        {
                            "node": "61937a3cd22f281386815fcd",
                            "position": {
                                "x": -4.05527,
                                "y": 0.300572,
                                "z": 9.552012
                            },
                            "surfaceNormal": {
                                "x": -1.87242,
                                "y": 5.841121,
                                "z": -0.011666
                            },
                            "_id": "6193898cb20dae117640910f"
                        }
                    ],
                    "uuid": "7dce0bd9-6ede-4e4f-b73c-3409e5bbf95f",
                    "attributes": {},
                    "id": "6193898cb20dae117640910e",
                    "attributeMetadata": [],
                }
            ],
            "ast": {
                "expr": {
                    "expr": {
                        "type": "AND",
                        "leftExpr": {
                            "expr": {
                                "type": {
                                    "values": [
                                        "TITLE"
                                    ]
                                },
                                "expr": {
                                    "value": "^tset.*$",
                                    "rawValue": "tset*",
                                    "type": "GLOBBING"
                                }
                            }
                        },
                        "rightExpr": {
                            "expr": {
                                "type": {
                                    "values": [
                                        "TAG"
                                    ]
                                },
                                "expr": {
                                    "value": "monday",
                                    "type": "STRING"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Success 200¶

Name	Type	Description
data	Array	Annotation list

Update an annotation¶

Parameter /annotation/update/:file/:annotation¶

Name	Type	Description
file	String	File id
annotation	String	Annotation id

POST /annotation/update/:file/:annotation¶

Name	Type	Description
name	String	Annotation name
content	String	Annotation content
color	String	Hex rgb color (ex: "#fff")
cameraTargetX	Number	Camera target X position of the annotation
cameraTargetY	Number	Camera target Y position of the annotation
cameraTargetZ	Number	Camera target Z position of the annotation
cameraX	Number	Camera X position of the annotation
cameraY	Number	Camera Y position of the annotation
cameraZ	Number	Camera Z position of the annotation
targets	Array	List of annotation targets
targetObjects	Array	List of annotation target objects
permissions	Object	Permissions of individual fields of the annotation
permissions.writeUuid	[String]	Permission to modify field `uuid` of the annotation
permissions.readUuid	[String]	Permission to read field `uuid` of the annotation
permissions.writeFolders	[String]	Permission to modify field `folders` of the annotation
permissions.readFolders	[String]	Permission to read field `folders` of the annotation
permissions.writeTargets	[String]	Permission to modify field `targets` of the annotation
permissions.readTargets	[String]	Permission to read field `targets` of the annotation
permissions.delete	[String]	Permission to delete the annotation
permissions.writeTitle	[String]	Permission to modify field `name` of the annotation
permissions.readTitle	[String]	Permission to read field `name` of the annotation
permissions.writeDiscussion	[String]	Permission to modify annotation comments
permissions.readDiscussion	[String]	Permission to read annotation comments
permissions.writeDescription	[String]	Permission to modify field `content` of the annotation
permissions.readDescription	[String]	Permission to read field `content` of the annotation
writePermissions	Array	Permissions required to modify the annotation
readPermissions	Array	Permissions required to read the annotation
folders	[String]	optional Folders this annotation belongs to

Example usage:

curl -X POST \
    https://smartshape.io/annotation/update/5bc09d1c26d4c90fe3e729ca/5bc09d4a3ce7db7aede25c5d/ \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "test",
        "cameraX": 45.00554,
        "cameraY": 25.04689,
        "cameraZ": 63.514038,
        "cameraTargetX": 5.00554,
        "cameraTargetY": 5.04689,
        "cameraTargetZ": 3.514038,
        "targets": [
            {
                "node": "5bc09d1c3fd9f525f390e937",
                "position": {
                    "x": 1.884846,
                    "y": -0.41996,
                    "z": -0.215639
                },
                "surfaceNormal": {
                    "x": 1,
                    "y": 0,
                    "z": 0
                }
            }
        ],
        "targetObjects": [
            {
                "node": "5bc09d1c3fd9f5254567e937",
                "position": {
                    "x": 12.884846,
                    "y": -50.215639,
                    "z": -30.41996
                }
            }
        ]
    }'

Success-Response:

HTTP/1.1 200 OK
{
    "success": true,
    "data": {
        "cameraX": 45.00554,
        "cameraY": 25.04689,
        "cameraZ": 63.514038,
        "cameraTargetX": 5.00554,
        "cameraTargetY": 5.04689,
        "cameraTargetZ": 3.514038,
        "name": "test",
        "content": "",
        "type": 0,
        "date": 1539349834138,
        "lastUpdate": 1539349834138,
        "file": "5bc09d1c26d4c90fe3e729ca",
        "author": "test@smartshape.io",
        "uuid": "90acf5e7-f990-454a-8f41-eb8707d4ecb0",
        "permissions": {
            "_id": "6193da06246dda3199e46b25",
            "writeUuid": [],
            "readUuid": [],
            "writeFolders": [],
            "readFolders": [],
            "writeTargets": [],
            "readTargets": [],
            "delete": [],
            "writeTitle": [],
            "readTitle": [],
            "writeDiscussion": [],
            "readDiscussion": [],
            "writeDescription": [],
            "readDescription": []
        },
        "writePermissions": [],
        "readPermissions": [],
        "folders": [],
        "tags": [],
        "targetObjects": [],
        "targets": [
            {
                "node": "5bc09d1c3fd9f525f390e937",
                "position": {
                    "x": 1.884846,
                    "y": -0.41996,
                    "z": -0.215639
                },
               "surfaceNormal": {
                   "x": 1,
                   "y": 0,
                   "z": 0
               }
            }
        ],
        "attributes": {},
        "id": "5bc09d4a3ce7db7aede25c5d"
    }
}

Success 200¶

Name	Type	Description
success	Bool
data	Array	Annotation list

Validate attributes update¶

Parameter /annotation/attribute/validate/:file¶

Name	Type	Description
file	String	File id

POST /annotation/attribute/validate/:file¶

Name	Type	Description
annotationId	String	The ID of the annotation to update
attributes	Object	Object that maps attribute keys to the corresponding updated value

Example usage:

curl -X POST \
  https://smartshape.io/annotation/attribute/validate/5c122a0a519da87cfb037980 \
  -H 'Authorization: Bearer <auth_token>' \
  -d '{
     "annotationId": "5c122a13faef856fd019c0fb",
     "attributes": {
       "TypeDefaut": "Coupé"
     }
  }'

Success-Response:

HTTP/1.1 200 OK
{
    "messages": [
        {
            "key": "TypeDefaut",
            "message": {
                "en_US": "A default type may not be specified if no remark type or no object type is specified.",
                "fr_FR": "Le type de défaut ne peut pas être renseigné sans qu'un type de remarque et un type d'objet ne soient renseignés."
            },
            "level": 3
        }
    ],
    "attributeMetadata": [
        {
            "id": "5c1a22348074992387810368",
            "key": "TypeDefaut",
            "label": {
                "fr_FR": "TypeDefaut",
                "en_US": "DefectType"
            },
            "validator": {
                "query": "(apply($incoming, @\"TypeDefaut\"=\"\" || (@\"TypeRemarque\"!=\"\" && @\"TypeObjet\"!=\"\")) && nth(array(-1), 0)) || nth(array(0), 0)",
                "messages": [
                    {
                        "level": 3,
                        "message": {
                            "fr_FR": "Le type de défaut ne peut pas être renseigné sans qu'un type de remarque et un type d'objet ne soient renseignés.",
                            "en_US": "A default type may not be specified if no remark type or no object type is specified."
                        }
                    }
                ]
            },
            "writePermissions": [],
            "readPermissions": [],
            "files": [
                "5c1a222699f4f81688cbfdbf"
            ]
        }
    ],
    "values": {
        "TypeDefaut": "Coupé"
    }
}

Success 200¶

Name	Type	Description
messages	[Object]	Array of localized error messages (may be empty)
attributeMetadata	[Object]	The list of updated AttributeMetadata resulting from the applied attributes changes
values	[Object]	The newly updated attributes

AnnotationMetadata¶

Create an AnnotationMetadata¶

POST /annotation/metadata/¶

Name	Type	Description
files	[String]	optional The file ids this AnnotationMetadata is attached to
defaultValue	String	optional Object that will replace the content of the Annotation matched by this AnnotationMetadata when the Annotation is updated/created.
matchQuery	String	optional SmartShapeQL query that: Is executed on each Annotation of the file. Must return a truthy or falsey value depending on if the Annotation Metadata applies to the Annotation or not.
labelQuery	String	optional SmartShapeQL query that: Is executed on each Annotation the Annotation Metadata applies to. Must return a string that will be the label of the Annotation shown at different places in the UI.
colorQuery	String	optional SmartShapeQL query that: Is executed on each Annotation the Annotation Metadata applies to. Must return an array containing two indices of colors in the client's color palette. First index is the outline color Second index is the center color.
shapeQuery	String	optional SmartShapeQL query that: Is executed on each Annotation the Annotation Metadata applies to. Must return the index of a shape as defined in this file: 0: circle. 1: square. 2: triangle. 3: diamond.

Example usage:

curl -X POST \
  https://smartshape.io/annotation/metadata \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "files": ["5de644b4bddb28460ef34400"],
    "matchQuery": "test",
    "labelQuery": "concat(get(., \"name\"), concat(\" is attached to an object made of \", apply(get(nth(get(., \"targets\"), 0), \"node\"), @\"material\")))"
  }'

Success-Response:

  HTTP/1.1 200 OK
{
    "matchQuery": "test",
    "labelQuery": "concat(get(., \"name\"), concat(\" is attached to an object made of \", apply(get(nth(get(., \"targets\"), 0), \"node\"), @\"material\")))",
    "files": [
        "5de644b4bddb28460ef34400"
    ],
    "id": "5de685d4ef568153ab20c876"
}

Success 200¶

Name	Type	Description
object	Object	The created AnnotationMetadata

Delete an AnnotationMetadata¶

Parameter /annotation/metadata/:annotationMetadata¶

Name	Type	Description
annotationMetadata	String	The id of the AnnotationMetadata to remove

Example usage:

curl -X DELETE \
  https://smartshape.io/annotation/metadata/5de685d4ef568153ab20c876 \
  -H 'Authorization: Bearer <auth_token>'

Success-Response:

HTTP/1.1 200 OK
{
    "success": true
}

List the AnnotationMetadatas¶

Parameter /annotation/metadata/:file¶

Name	Type	Description
file	String	The file id the listed AnnotationMetadatas must be restricted to

Example usage:

curl -X GET \
  https://smartshape.io/annotation/metadata/5de644b4bddb28460ef34400 \
  -H 'Authorization: Bearer <auth_token>'

Success-Response:

HTTP/1.1 200 OK
[
   {
       "labelQuery": "concat(get(., \"name\"), concat(\" is attached to an object made of \", apply(get(nth(get(., \"targets\"), 0), \"node\"), @\"material\")))",
       "matchQuery": "test - edit",
       "files": [
           "5de644b4bddb28460ef34400"
       ],
       "id": "5de685d4ef568153ab20c876"
   }
]

Success 200¶

Name	Type	Description
objects	[Object]	The AnnotationMetadatas

Update an AnnotationMetadata¶

Parameter /annotation/metadata/:annotationMetadata¶

Name	Type	Description
annotationMetadata	String	The id of the AnnotationMetadata to update

POST /annotation/metadata/:annotationMetadata¶

Name	Type	Description
files	[String]	optional The file ids this AnnotationMetadata is attached to
matchQuery	String	optional A query to filter the Annotations matched by this AnnotationMetadata
labelQuery	String	optional A query to format the Annotation.label of every Annotation matched by this AnnotationMetadata

Example usage:

curl -X PUT \
  https://smartshape.io/annotation/metadata \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "matchQuery": "test - edit"
  }'

Success-Response:

  HTTP/1.1 200 OK
{
    "matchQuery": "test - edit",
    "labelQuery": "concat(get(., \"name\"), concat(\" is attached to an object made of \", apply(get(nth(get(., \"targets\"), 0), \"node\"), @\"material\")))",
    "files": [
        "5de644b4bddb28460ef34400"
    ],
    "id": "5de685d4ef568153ab20c876"
}

Success 200¶

Name	Type	Description
object	Object	The updated AnnotationMetadata

April 27, 2023 April 27, 2023

Annotation API

Annotation¶

Add an annotation comment¶

Parameter /annotation/comment/:file/:annotation¶

POST /annotation/comment/:file/:annotation¶

Success 200¶

Add or update annotation attributes¶

Parameter /annotation/attributes/:file¶

POST /annotation/attributes/:file¶

Success 200¶

Create an annotation¶

Parameter /annotation/create/:file¶

POST /annotation/create/:file¶

Success 200¶

Create an annotation search form¶

POST /annotation/search/form/¶

Success 200¶

Delete an annotation¶

Parameter /annotation/delete/:file/:annotation¶

Success 200¶

Delete an annotation search form¶

Parameter /annotation/search/form/:searchform¶

Success 200¶

List annotation comments¶

Parameter /annotation/comment/:file/:annotation¶

Success 200¶

List annotation search forms¶

Parameter /annotation/search/form/:file¶

List annotations¶

Parameter /annotation/list/:file¶

GET /annotation/list/:file¶

Success 200¶

Search for annotations¶

Parameter /annotation/search/:file¶

POST /annotation/search/:file¶

Success 200¶

Update an annotation¶

Parameter /annotation/update/:file/:annotation¶

POST /annotation/update/:file/:annotation¶

Success 200¶

Validate attributes update¶

Parameter /annotation/attribute/validate/:file¶

POST /annotation/attribute/validate/:file¶

Success 200¶

AnnotationMetadata¶

Create an AnnotationMetadata¶

POST /annotation/metadata/¶

Success 200¶

Delete an AnnotationMetadata¶

Parameter /annotation/metadata/:annotationMetadata¶

List the AnnotationMetadatas¶

Parameter /annotation/metadata/:file¶

Success 200¶

Update an AnnotationMetadata¶

Parameter /annotation/metadata/:annotationMetadata¶

POST /annotation/metadata/:annotationMetadata¶

Success 200¶