Diagrams

Create or update a diagram

Creates a diagram entity from either a raw tldraw snapshot or structured input, and optionally links it to a host entity. Typical draw.io import flow: (1) convert XML via POST /convert/drawio-to-tldraw, (2) call this endpoint with the returned snapshot plus a hostEntityId, (3) optionally embed the diagram in the host’s rich-text field (e.g. description) by appending a node of the form {"type": "tldraw", "diagramId": "<id>", "children": [{"text": ""}]} via PUT /project//entities//values — embeds only resolve diagrams linked to the entity that owns the field. Upsert semantics: re-POSTing with the same id replaces that diagram’s name and snapshot in place (e.g. re-importing an updated source file); an id belonging to a non-diagram entity is rejected with 409.

POST

project

{projectId}

diagrams

Create or update a diagram

curl --request POST \
  --url https://backend.branch.flowengineering.com/project/{projectId}/diagrams \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'customer: <customer>' \
  --data '
{
  "name": "<string>",
  "annotations": [
    {
      "id": "<string>",
      "text": "<string>",
      "color": "<string>",
      "x": 123,
      "y": 123
    }
  ],
  "branchId": "<string>",
  "connections": [
    {
      "from": "<string>",
      "to": "<string>",
      "color": "<string>",
      "label": "<string>"
    }
  ],
  "entities": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "childColumns": 123,
      "parentId": "<string>"
    }
  ],
  "hostEntityId": "<string>",
  "id": "<string>",
  "nodes": [
    {
      "id": "<string>",
      "name": "<string>",
      "childColumns": 123,
      "color": "<string>",
      "h": 123,
      "parentId": "<string>",
      "w": 123,
      "x": 123,
      "y": 123
    }
  ]
}
'

import requests

url = "https://backend.branch.flowengineering.com/project/{projectId}/diagrams"

payload = {
    "name": "<string>",
    "annotations": [
        {
            "id": "<string>",
            "text": "<string>",
            "color": "<string>",
            "x": 123,
            "y": 123
        }
    ],
    "branchId": "<string>",
    "connections": [
        {
            "from": "<string>",
            "to": "<string>",
            "color": "<string>",
            "label": "<string>"
        }
    ],
    "entities": [
        {
            "id": "<string>",
            "name": "<string>",
            "type": "<string>",
            "childColumns": 123,
            "parentId": "<string>"
        }
    ],
    "hostEntityId": "<string>",
    "id": "<string>",
    "nodes": [
        {
            "id": "<string>",
            "name": "<string>",
            "childColumns": 123,
            "color": "<string>",
            "h": 123,
            "parentId": "<string>",
            "w": 123,
            "x": 123,
            "y": 123
        }
    ]
}
headers = {
    "customer": "<customer>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    customer: '<customer>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    annotations: [{id: '<string>', text: '<string>', color: '<string>', x: 123, y: 123}],
    branchId: '<string>',
    connections: [{from: '<string>', to: '<string>', color: '<string>', label: '<string>'}],
    entities: [
      {
        id: '<string>',
        name: '<string>',
        type: '<string>',
        childColumns: 123,
        parentId: '<string>'
      }
    ],
    hostEntityId: '<string>',
    id: '<string>',
    nodes: [
      {
        id: '<string>',
        name: '<string>',
        childColumns: 123,
        color: '<string>',
        h: 123,
        parentId: '<string>',
        w: 123,
        x: 123,
        y: 123
      }
    ]
  })
};

fetch('https://backend.branch.flowengineering.com/project/{projectId}/diagrams', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "formulaTemplates": {},
  "formulas": {},
  "id": "<string>",
  "links": {
    "crosslinks": [
      "<string>"
    ],
    "inbound": [
      "<string>"
    ],
    "inboundOrder": {},
    "outbound": [
      "<string>"
    ],
    "inboundTypes": {},
    "outboundOrder": {},
    "outboundTypes": {},
    "rootPlaced": true
  },
  "values": {},
  "branchesChangedIn": [
    "<string>"
  ],
  "branchesCreatedIn": [
    "<string>"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "defaultSortKey": "<string>",
  "deleted": true,
  "type": "<string>",
  "uniqueEntityNumber": 123,
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

X-API-Key

string

header

required

Headers

customer

string

required

Workspace identifier

Path Parameters

projectId

string

required

Body

application/json

name

string

required

Diagram title

annotations

object[]

Freestanding text annotations (titles, section labels)

Show child attributes

branchId

string

Branch to write to. Omit or pass "master" for the base branch.

connections

object[]

Directed arrows between entity/node IDs

Show child attributes

entities

object[]

Flow platform entities to render as data-shape cards (entity relationship diagrams). For generic shapes use nodes instead.

Show child attributes

hostEntityId

string

Entity to link the diagram to. The diagram appears in this entity's Diagrams section, and rich-text embeds ({"type": "tldraw", ...} nodes) only resolve diagrams linked to the entity that owns the field — pass this whenever the diagram should be visible from an existing entity.

string

Diagram entity ID (UUID). Auto-generated if omitted. If an existing diagram entity has this ID, its name and snapshot are replaced (upsert); if a non-diagram entity has this ID the request fails with 409.

nodes

object[]

Standalone geometric nodes not backed by Flow entities (state machines, flowcharts). Provide x/y on every node for a controlled layout.

Show child attributes

snapshot

object

Pre-built tldraw snapshot to persist verbatim — exactly the snapshot object returned by POST /convert/drawio-to-tldraw. Mutually exclusive with entities/nodes/connections/annotations.

Show child attributes

Response

201 - application/json

formulaTemplates

object

required

formulas

object

required

Show child attributes

string

required

links

object

required

Show child attributes

values

object

required

branchesChangedIn

string[]

branchesCreatedIn

string[]

createdAt

string<date-time>

defaultSortKey

string

deleted

boolean

type

string

uniqueEntityNumber

number

updatedAt

string<date-time>

Create or update a diagram

curl --request POST \
  --url https://backend.branch.flowengineering.com/project/{projectId}/diagrams \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'customer: <customer>' \
  --data '
{
  "name": "<string>",
  "annotations": [
    {
      "id": "<string>",
      "text": "<string>",
      "color": "<string>",
      "x": 123,
      "y": 123
    }
  ],
  "branchId": "<string>",
  "connections": [
    {
      "from": "<string>",
      "to": "<string>",
      "color": "<string>",
      "label": "<string>"
    }
  ],
  "entities": [
    {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "childColumns": 123,
      "parentId": "<string>"
    }
  ],
  "hostEntityId": "<string>",
  "id": "<string>",
  "nodes": [
    {
      "id": "<string>",
      "name": "<string>",
      "childColumns": 123,
      "color": "<string>",
      "h": 123,
      "parentId": "<string>",
      "w": 123,
      "x": 123,
      "y": 123
    }
  ]
}
'

import requests

url = "https://backend.branch.flowengineering.com/project/{projectId}/diagrams"

payload = {
    "name": "<string>",
    "annotations": [
        {
            "id": "<string>",
            "text": "<string>",
            "color": "<string>",
            "x": 123,
            "y": 123
        }
    ],
    "branchId": "<string>",
    "connections": [
        {
            "from": "<string>",
            "to": "<string>",
            "color": "<string>",
            "label": "<string>"
        }
    ],
    "entities": [
        {
            "id": "<string>",
            "name": "<string>",
            "type": "<string>",
            "childColumns": 123,
            "parentId": "<string>"
        }
    ],
    "hostEntityId": "<string>",
    "id": "<string>",
    "nodes": [
        {
            "id": "<string>",
            "name": "<string>",
            "childColumns": 123,
            "color": "<string>",
            "h": 123,
            "parentId": "<string>",
            "w": 123,
            "x": 123,
            "y": 123
        }
    ]
}
headers = {
    "customer": "<customer>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    customer: '<customer>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    annotations: [{id: '<string>', text: '<string>', color: '<string>', x: 123, y: 123}],
    branchId: '<string>',
    connections: [{from: '<string>', to: '<string>', color: '<string>', label: '<string>'}],
    entities: [
      {
        id: '<string>',
        name: '<string>',
        type: '<string>',
        childColumns: 123,
        parentId: '<string>'
      }
    ],
    hostEntityId: '<string>',
    id: '<string>',
    nodes: [
      {
        id: '<string>',
        name: '<string>',
        childColumns: 123,
        color: '<string>',
        h: 123,
        parentId: '<string>',
        w: 123,
        x: 123,
        y: 123
      }
    ]
  })
};

fetch('https://backend.branch.flowengineering.com/project/{projectId}/diagrams', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "formulaTemplates": {},
  "formulas": {},
  "id": "<string>",
  "links": {
    "crosslinks": [
      "<string>"
    ],
    "inbound": [
      "<string>"
    ],
    "inboundOrder": {},
    "outbound": [
      "<string>"
    ],
    "inboundTypes": {},
    "outboundOrder": {},
    "outboundTypes": {},
    "rootPlaced": true
  },
  "values": {},
  "branchesChangedIn": [
    "<string>"
  ],
  "branchesCreatedIn": [
    "<string>"
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "defaultSortKey": "<string>",
  "deleted": true,
  "type": "<string>",
  "uniqueEntityNumber": 123,
  "updatedAt": "2023-11-07T05:31:56Z"
}

Quickstart

Examples

Automations

Flow MCP

Endpoints

Create or update a diagram

Authorizations

Headers

Path Parameters

Body

Response