Attachments: API for elements attachments

What are Attachments?

Attachments are objects that are attached to another object, grouped.

This set of APIs is a programmatic implementation of the attachment operations done manually in a workspace: you drag an object A over other object B until the border of the object B highlighted (around 1 second). At this moment you drop the object A and it is attached to object B: when you move object B, the object A moves along with it.

One advantage is that you can specify the attachment coordinates for where the object will be located into the surface you are attaching it to, the object is automatically moved.

Visually, in the Workspace, when executing an Attachment API, you will see how the object is automatically moved into the surface it is attached to and a yellow fading border appears around the attached object. When deleting an Attachment, you will see a blue fading border around the object that was unattached.

Highlights of Attachments

Allowed Element types for Attachments:

ELEMENT ALLOWED ELEMENT TYPE FOR ATTACHMENT
Note
  • Note
  • Image
  • Browser
  • Document
  • Text
  • Video
Image
  • Note
  • Image
  • Browser
  • Document
  • Text
  • Video
Document
  • Note
  • Image
  • Browser
  • Document
  • Text
  • Video
Browser
  • Note
  • Image
  • Browser
  • Document
  • Text
  • Video
Video
  • Note
  • Image
  • Browser
  • Document
  • Text
  • Video
Text No elements can be attached to text, but text can be attached to other elements.
Canvas No elements can be attached to canvas. Elements that are posted inside canvas creates membership, not adhesion.

How to implement Attachments APIs?

Create: attachment an element to another element

Endpoint /v2/workspaces/<workspace_uid>/elements/<surface_type>/<surface_id>/attachments
Method POST
Comments

Sample Request Body to add an object to an image:

  • Note sourceId "YYYYYYYYY" at coordinates [10,10]
  • image: is defined in the API call: by /<surface_type>/<surface_id>/ (/image/XXXXXXXXX/ in the example below)
        
    {
        "x": 10,
        "y": 10,
        "sourceId": "YYYYYYYYY"
    }

Sample Response Body:
    {
        "x": 10,
        "y": 10,
        "source": {
        "id": "YYYYYYYYY",
        "type": "note"
        },
        "surface": {
        "id": "XXXXXXXXX",
        "type": "image"
        }
    }

Get the list of attachments for an element

Endpoint /v2/workspaces/<workspace_uid>/elements/<surface_type>/<surface_id>/attachments
Method GET
Comments

Sample Response Body with the list of attachements an object has:

   
...         
{
    "attachments": [{
    "id": "46degdftjd887d",
    "type": "note"
    },
    {
    "id": "jfhy5yttut89aa",
    "type": "image"
    },
    {
    "id": "ysrethdutr2ej",
    "type": "text"
    }]
}
...

Delete attachments in an element

Endpoint /v2/workspaces/<workspace_uid>/elements/<surface_type>/<surface_id>/attachments/<target_id>
Method DELETE
Comments

Sample Response Body after deleting the attachments in an element:

{
  "message": "Attachment {target_id} has been removed from the surface {surface_id}"
}  


If you have any questions or comments, please contact us at Bluescape support.