Aller au contenu

Annotation API

Annotation

Add or update annotation attributes

Url: POST /annotation/attributes/:file

Parameter

Name Type Description
file String

File id

Body

Name Type Description
JSON Object

object describing the attributes to add or update

Success 200

Name Type Description
result String

JSON object of the updated nodes
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"
    }
]

Error 4xx

Name Type Description
400

Missing argument
500

Internal Error
503

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

Create an annotation

Url: POST /annotation/create/:file

Parameter

Name Type Description
file String

File id

Body

Name Type Description
name String

Annotation name
content String optional

Annotation content
cameraTargetX Number optional

Camera target X position of the annotation
cameraTargetY Number optional

Camera target Y position of the annotation
cameraTargetZ Number optional

Camera target Z position of the annotation
cameraX Number optional

Camera X position of the annotation
cameraY Number optional

Camera Y position of the annotation
cameraZ Number optional

Camera Z position of the annotation
targets Object[] optional

List of annotation targets
targetObjects Object[] optional

List of annotation target objects
permissions Object optional

Permissions of individual fields of the annotation
permissions.writeUuid String[] optional

Permission to modify field uuid of the annotation
permissions.readUuid String[] optional

Permission to read field uuid of the annotation
permissions.writeFolders String[] optional

Permission to modify field folders of the annotation
permissions.readFolders String[] optional

Permission to read field folders of the annotation
permissions.writeTargets String[] optional

Permission to modify field targets of the annotation
permissions.readTargets String[] optional

Permission to read field targets of the annotation
permissions.delete String[] optional

Permission to delete the annotation
permissions.writeTitle String[] optional

Permission to modify field name of the annotation
permissions.readTitle String[] optional

Permission to read field name of the annotation
permissions.writeDiscussion String[] optional

Permission to modify annotation comments
permissions.readDiscussion String[] optional

Permission to read annotation comments
permissions.writeDescription String[] optional

Permission to modify field content of the annotation
permissions.readDescription String[] optional

Permission to read field content of the annotation
writePermissions String[] optional

Permissions required to modify the annotation
readPermissions String[] optional

Permissions required to read the annotation
folders String[] optional

Folders this annotation belongs to

Success 200

Name Type Description
success Boolean
data Object

Annotation
data.file String

File id
data.name String

Annotation name
data.content String optional

Annotation content
data.cameraTargetX Number optional

Camera target X position of the annotation
data.cameraTargetY Number optional

Camera target Y position of the annotation
data.cameraTargetZ Number optional

Camera target Z position of the annotation
data.cameraX Number optional

Camera X position of the annotation
data.cameraY Number optional

Camera Y position of the annotation
data.cameraZ Number optional

Camera Z position of the annotation
data.targets Object[] optional

List of annotation targets
data.targetObjects Object[] optional

List of annotation target objects
data.permissions Object optional

Permissions of individual fields of the annotation
data.permissions.writeUuid String[] optional

Permission to modify field uuid of the annotation
data.permissions.readUuid String[] optional

Permission to read field uuid of the annotation
data.permissions.writeFolders String[] optional

Permission to modify field folders of the annotation
data.permissions.readFolders String[] optional

Permission to read field folders of the annotation
data.permissions.writeTargets String[] optional

Permission to modify field targets of the annotation
data.permissions.readTargets String[] optional

Permission to read field targets of the annotation
data.permissions.delete String[] optional

Permission to delete the annotation
data.permissions.writeTitle String[] optional

Permission to modify field name of the annotation
data.permissions.readTitle String[] optional

Permission to read field name of the annotation
data.permissions.writeDiscussion String[] optional

Permission to modify annotation comments
data.permissions.readDiscussion String[] optional

Permission to read annotation comments
data.permissions.writeDescription String[] optional

Permission to modify field content of the annotation
data.permissions.readDescription String[] optional

Permission to read field content of the annotation
data.writePermissions String[] optional

Permissions required to modify the annotation
data.readPermissions String[] optional

Permissions required to read the annotation
data.folders String[] optional

Folders this annotation belongs to
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": {},
        "attributeMetadata": [],
        "id": "5bc0b05b50fa6c26a9610f24"
    }
}

Error 4xx

Name Type Description
404

Not found
503

Unauthorized
Example usage: 
curl -X POST \
    https://smartshape.io/annotation/create/5bb60111e75d6d0fd21fe239 \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'X-SmartShape-Session: <session_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
                }
            }
        ]
    }'

Delete an annotation

Url: DELETE /annotation/delete/:file/:annotation

Parameter

Name Type Description
file String

File id
annotation String

Annotation id

Success 200

Name Type Description
success Boolean
Success-Response: 
HTTP/1.1 200 OK
{
    "success":true
}

Error 4xx

Name Type Description
404

Not found
503

Unauthorized
Example usage: 
curl -X DELETE -H 'Authorization: Bearer <auth_token>' -H 'X-SmartShape-Session: <session_token>' https://smartshape.io/annotation/delete/58d3aa7c0868c419e48af374/58d3d42cd08d7c1987feb3bd"

List annotations

Url: GET /annotation/list/:file

Parameter

Name Type Description
file String

File id
#### GET
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

Success 200

Name Type Description
success Boolean
data Object[]

Annotations
data.file String

File id
data.name String

Annotation name
data.content String optional

Annotation content
data.cameraTargetX Number optional

Camera target X position of the annotation
data.cameraTargetY Number optional

Camera target Y position of the annotation
data.cameraTargetZ Number optional

Camera target Z position of the annotation
data.cameraX Number optional

Camera X position of the annotation
data.cameraY Number optional

Camera Y position of the annotation
data.cameraZ Number optional

Camera Z position of the annotation
data.targets Object[] optional

List of annotation targets
data.targets.id String

ID of the target
data.targets._id String

ID of the target
data.targets.node String optional

Node the target is put on
data.targets.subsurfaceId Number optional

ID of the subsurface the target is put on
data.targets.surfaceUuid String optional

UUID of the subsurface the target is put on
data.targets.nodeName String optional

Name of the Node the target is put on
data.targets.position Object

Position of the target
data.targets.position.x Number optional

X coordinate of the target
data.targets.position.y Number optional

Y coordinate of the target
data.targets.position.z Number optional

Z coordinate of the target
data.targets.surfaceNormal Object optional

Normal of the surface the target is put on
data.targets.surfaceNormal.x Number optional

X coordinate of the normal of the surface the target is put on
data.targets.surfaceNormal.y Number optional

Y coordinate of the normal of the surface the target is put on
data.targets.surfaceNormal.z Number optional

Z coordinate of the normal of the surface the target is put on
data.targetObjects Object[] optional

List of annotation target objects
data.permissions Object optional

Permissions of individual fields of the annotation
data.permissions.writeUuid String[] optional

Permission to modify field uuid of the annotation
data.permissions.readUuid String[] optional

Permission to read field uuid of the annotation
data.permissions.writeFolders String[] optional

Permission to modify field folders of the annotation
data.permissions.readFolders String[] optional

Permission to read field folders of the annotation
data.permissions.writeTargets String[] optional

Permission to modify field targets of the annotation
data.permissions.readTargets String[] optional

Permission to read field targets of the annotation
data.permissions.delete String[] optional

Permission to delete the annotation
data.permissions.writeTitle String[] optional

Permission to modify field name of the annotation
data.permissions.readTitle String[] optional

Permission to read field name of the annotation
data.permissions.writeDiscussion String[] optional

Permission to modify annotation comments
data.permissions.readDiscussion String[] optional

Permission to read annotation comments
data.permissions.writeDescription String[] optional

Permission to modify field content of the annotation
data.permissions.readDescription String[] optional

Permission to read field content of the annotation
data.writePermissions String[] optional

Permissions required to modify the annotation
data.readPermissions String[] optional

Permissions required to read the annotation
data.folders String[]

Folders this annotation belongs to
data.uuid String

UUID of the Annotation
data.date Number

Date of creation of the Annotation
data.lastUpdate Number

Date of last update of the Annotation
data.author String

Author of the Annotation
data.tags String[] optional

Tags of the Annotation
data.attributes Object optional

Attributes of the Annotation
data.unreadComments Number optional

Number of unread comments of the Annotation
data.attributeMetadata Object[] optional

AttributeMetadata that apply to the Annotation
data.color Number[] optional

Colors of the targets of the Annotation
data.shape Number optional

Shape of the targets of the Annotation
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.",
            "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": [
                {
                    "position": {
                        "x": 3.821942,
                        "y": 6.396293,
                        "z": 4.446007
                    },
                    "_id": "61938a19b20dae117640916c",
                    "id": "61938a19b20dae117640916c"
                }
            ],
            "attributes": {},
            "id": "61938a19b20dae117640916b",
            "unreadComments": 0,
            "attributeMetadata": [],
            "label": "Window is attached to an object made of undefined"
        }
    ]
}

Error 4xx

Name Type Description
404

Not found
503

Unauthorized
Example usage: 
curl -X GET -H 'Authorization: Bearer <auth_token>' -H 'X-SmartShape-Session: <session_token>' 'https://smartshape.io/annotation/list/619379e595dff80f314dcbdd'
Example usage: Exclude the unreadComments property. 
curl -X GET -H 'Authorization: Bearer <auth_token>' -H 'X-SmartShape-Session: <session_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>' -H 'X-SmartShape-Session: <session_token>' 'https://smartshape.io/annotation/list/619379e595dff80f314dcbdd?format=xlsx'

Search for annotations

Url: POST /annotation/search/:file

Parameter

Name Type Description
file String

File id

Body

Name Type Description
queries String[]

Search queries.

Success 200

Name Type Description
data Array

Annotation list
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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Error 4xx

Name Type Description
400

Bad request
404

Not found
503

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

Update an annotation

Url: POST /annotation/update/:file/:annotation

Parameter

Name Type Description
file String

File id
annotation String

Annotation id

Body

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

Success 200

Name Type Description
success Boolean
data Array

Annotation list
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": {},
        "attributeMetadata": [],
        "id": "5bc09d4a3ce7db7aede25c5d"
    }
}

Error 4xx

Name Type Description
404

Not found
503

Unauthorized
Example usage: 
curl -X POST \
    https://smartshape.io/annotation/update/5bc09d1c26d4c90fe3e729ca/5bc09d4a3ce7db7aede25c5d/ \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'X-SmartShape-Session: <session_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
                }
            }
        ]
    }'

Validate attributes update

Url: POST /annotation/attribute/validate/:file

Parameter

Name Type Description
file String

File id

Body

Name Type Description
annotationId String optional

The ID of the annotation to update
annotationName String optional

The name of the annotation not yet created, ignored if annotationId exists
attributes Object

Object that maps attribute keys to the corresponding updated value

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
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é"
    }
}

Error 4xx

Name Type Description
400

Missing argument
500

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

AnnotationComment

Add an annotation comment

Url: POST /annotation/comment/:file/:annotation

Parameter

Name Type Description
file String

File id
annotation String

Annotation id

Body

Name Type Description
message String

Annotation comment message

Success 200

Name Type Description
success Boolean
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
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"
    }
}

Error 4xx

Name Type Description
404

Not found
503

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

List annotation comments

Url: GET /annotation/comment/:file/:annotation

Parameter

Name Type Description
file String

File id
annotation String

Annotation id

Success 200

Name Type Description
success Boolean
data Array

Annotation comments list
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
        }
    ]
}

Error 4xx

Name Type Description
404

Not found
503

Unauthorized
Example usage: 
curl -X GET -H 'Authorization: Bearer <auth_token>' -H 'X-SmartShape-Session: <session_token>' 'https://smartshape.io/annotation/comment/619379e595dff80f314dcbdd/6193898cb20dae117640910e'

AnnotationMetadata

Create an AnnotationMetadata

Url: POST /annotation/metadata/

Body

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.

Success 200

Name Type Description
id String

The ID of the created AnnotationMetadata
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.

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"
}

Error 4xx

Name Type Description
500

Internal Error
Example usage: 
curl -X POST \
  https://smartshape.io/annotation/metadata \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'X-SmartShape-Session: <session_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\")))"
  }'

Delete an AnnotationMetadata

Url: DELETE /annotation/metadata/:annotationMetadata

Parameter

Name Type Description
annotationMetadata String

The id of the AnnotationMetadata to remove
Success-Response: 
HTTP/1.1 200 OK
{
    "success": true
}

Error 4xx

Name Type Description
500

Internal Error
Example usage: 
curl -X DELETE \
  https://smartshape.io/annotation/metadata/5de685d4ef568153ab20c876 \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'X-SmartShape-Session: <session_token>'

List the AnnotationMetadatas

Url: GET /annotation/metadata/:file

Parameter

Name Type Description
file String

The file id the listed AnnotationMetadatas must be restricted to

Success 200

Name Type Description
objects Object[]

The AnnotationMetadatas
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"
   }
]

Error 4xx

Name Type Description
500

Internal Error
Example usage: 
curl -X GET \
  https://smartshape.io/annotation/metadata/5de644b4bddb28460ef34400 \
  -H 'Authorization: Bearer <auth_token>' \
  -H 'X-SmartShape-Session: <session_token>'

Update an AnnotationMetadata

Url: PUT /annotation/metadata/:annotationMetadata

Parameter

Name Type Description
annotationMetadata String

The id of the AnnotationMetadata to update

Body

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

Success 200

Name Type Description
object Object

The updated AnnotationMetadata
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"
}

Error 4xx

Name Type Description
500

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

AnnotationSearchForm

Create an annotation search form

Url: POST /annotation/search/form/

Body

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

Success 200

Name Type Description
result Object

JSON object of the created annotation search forms
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"
}

Error 4xx

Name Type Description
400

Invalid fields provided
500

ValidationError
Example usage: 
curl -X POST \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'X-SmartShape-Session: <session_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": []
    }'

Delete an annotation search form

Url: DELETE /annotation/search/form/:searchform

Parameter

Name Type Description
searchform String

Annotation search form id

Success 200

Name Type Description
ID String

of the deleted search form
Success-Response: 
HTTP/1.1 200 OK
"5c4ae40dc97a4b690dd4caad"

Error 4xx

Name Type Description
404

Not found
503

Unauthorized
Example usage: 
curl -X DELETE \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'X-SmartShape-Session: <session_token>' \
    'https://smartshape.io/annotation/search/form/5fff02ed87d3c866709c16a4'

List annotation search forms

Url: GET /annotation/search/form/:file

Parameter

Name Type Description
file String optional

File id
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"
    }
]
Example usage: 
curl -X GET \
    -H 'Authorization: Bearer <auth_token>' \
    -H 'X-SmartShape-Session: <session_token>' \
    'https://smartshape.io/annotation/search/form/5fff02ed87d3c866709c16a4'
September 11, 2024 September 11, 2024