Annotation API
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 |
permissions.readUuid | String[] | optional Permission to read field |
permissions.writeFolders | String[] | optional Permission to modify field |
permissions.readFolders | String[] | optional Permission to read field |
permissions.writeTargets | String[] | optional Permission to modify field |
permissions.readTargets | String[] | optional Permission to read field |
permissions.delete | String[] | optional Permission to delete the annotation |
permissions.writeTitle | String[] | optional Permission to modify field |
permissions.readTitle | String[] | optional Permission to read field |
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 |
permissions.readDescription | String[] | optional Permission to read field |
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 |
data.permissions.readUuid | String[] | optional Permission to read field |
data.permissions.writeFolders | String[] | optional Permission to modify field |
data.permissions.readFolders | String[] | optional Permission to read field |
data.permissions.writeTargets | String[] | optional Permission to modify field |
data.permissions.readTargets | String[] | optional Permission to read field |
data.permissions.delete | String[] | optional Permission to delete the annotation |
data.permissions.writeTitle | String[] | optional Permission to modify field |
data.permissions.readTitle | String[] | optional Permission to read field |
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 |
data.permissions.readDescription | String[] | optional Permission to read field |
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 |
Error 4xx¶
Name | Type | Description |
---|---|---|
404 | Not found |
|
503 | Unauthorized |
Example usage:
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: |
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 |
data.permissions.readUuid | String[] | optional Permission to read field |
data.permissions.writeFolders | String[] | optional Permission to modify field |
data.permissions.readFolders | String[] | optional Permission to read field |
data.permissions.writeTargets | String[] | optional Permission to modify field |
data.permissions.readTargets | String[] | optional Permission to read field |
data.permissions.delete | String[] | optional Permission to delete the annotation |
data.permissions.writeTitle | String[] | optional Permission to modify field |
data.permissions.readTitle | String[] | optional Permission to read field |
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 |
data.permissions.readDescription | String[] | optional Permission to read field |
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:
Example usage: Exclude the unreadComments property.
Example usage: Export the results as XLSX file.
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:
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 |
permissions.readUuid | String[] | Permission to read field |
permissions.writeFolders | String[] | Permission to modify field |
permissions.readFolders | String[] | Permission to read field |
permissions.writeTargets | String[] | Permission to modify field |
permissions.readTargets | String[] | Permission to read field |
permissions.delete | String[] | Permission to delete the annotation |
permissions.writeTitle | String[] | Permission to modify field |
permissions.readTitle | String[] | Permission to read field |
permissions.writeDiscussion | String[] | Permission to modify annotation comments |
permissions.readDiscussion | String[] | Permission to read annotation comments |
permissions.writeDescription | String[] | Permission to modify field |
permissions.readDescription | String[] | Permission to read field |
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:
title: "AnnotationComment API"¶
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:
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:
title: "AnnotationMetadata API"¶
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:
|
labelQuery | String | optional SmartShapeQL query that:
|
colorQuery | String | optional SmartShapeQL query that:
|
shapeQuery | String | optional SmartShapeQL query that:
|
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:
|
labelQuery | String | optional SmartShapeQL query that:
|
colorQuery | String | optional SmartShapeQL query that:
|
shapeQuery | String | optional SmartShapeQL query that:
|
Success-Response:
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 |
Error 4xx¶
Name | Type | Description |
---|---|---|
500 | Internal Error |
Example usage:
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:
Error 4xx¶
Name | Type | Description |
---|---|---|
500 | Internal Error |
Example usage:
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:
Error 4xx¶
Name | Type | Description |
---|---|---|
500 | Internal Error |
Example usage:
title: "AnnotationSearchForm API"¶
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 |
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. |
fields.data | String[] | optional Values showed in the drop down menu when the type is |
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 |
Error 4xx¶
Name | Type | Description |
---|---|---|
404 | Not found |
|
503 | Unauthorized |
Example usage:
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"
}
]