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.

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 /v1/workspaces/<workspace_id>/elements/<surface_type>/<surface_id>/attachments
Method POST
Comments

Sample Request Body to add an attachment (element "ysrethdutr2ej" at coordinates [10,10]) to the surface or element specified in the API call:

    {
        "x": 10,
        "y": 10,
        "sourceId": "ysrethdutr2ej"
    }

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

Get the list of attachments for an element

Endpoint /v1/workspaces/<workspace_id>/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 /v1/workspaces/<workspace_id>/elements/<surface_type>/<surface_id>/attachments
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.