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