> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowengineering.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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/{projectId}/entities/{entityId}/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.



## OpenAPI

````yaml /openapi/customer-api.json post /project/{projectId}/diagrams
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Flow customer API reference. Start with the [quickstart](/api/quickstart)
    and [authentication guide](/api/authentication).
  title: Customer API
  version: 1.0.0
servers:
  - description: Flow API
    url: https://backend.branch.flowengineering.com
security: []
tags:
  - name: Automations
  - name: Branches
  - name: Comments
  - name: Convert
  - name: Data Model
  - name: Diagrams
  - name: Entities
  - name: Files
  - name: Import
  - name: Notifications
  - name: Projects
  - name: ReqIF
  - name: ReqIF Import
  - name: Shared Access Grants
  - name: User Groups
  - name: Users
paths:
  /project/{projectId}/diagrams:
    post:
      tags:
        - Diagrams
      summary: Create or update a diagram
      description: >-
        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/{projectId}/entities/{entityId}/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.
      operationId: DiagramsController_createDiagram
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: string
        - description: Workspace identifier
          in: header
          name: customer
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDiagramDto'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityStateResponseDto'
          description: ''
      security:
        - api-key: []
        - bearer: []
components:
  schemas:
    CreateDiagramDto:
      properties:
        annotations:
          description: Freestanding text annotations (titles, section labels)
          items:
            $ref: '#/components/schemas/DiagramAnnotationItemDto'
          type: array
        branchId:
          description: Branch to write to. Omit or pass "master" for the base branch.
          type: string
        connections:
          description: Directed arrows between entity/node IDs
          items:
            $ref: '#/components/schemas/DiagramConnectionItemDto'
          type: array
        entities:
          description: >-
            Flow platform entities to render as data-shape cards (entity
            relationship diagrams). For generic shapes use `nodes` instead.
          items:
            $ref: '#/components/schemas/DiagramEntityItemDto'
          type: array
        hostEntityId:
          description: >-
            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.
          type: string
        id:
          description: >-
            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.
          type: string
        name:
          description: Diagram title
          type: string
        nodes:
          description: >-
            Standalone geometric nodes not backed by Flow entities (state
            machines, flowcharts). Provide x/y on every node for a controlled
            layout.
          items:
            $ref: '#/components/schemas/DiagramNodeItemDto'
          type: array
        snapshot:
          allOf:
            - $ref: '#/components/schemas/DiagramSnapshotDto'
          description: >-
            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.
      required:
        - name
      type: object
    EntityStateResponseDto:
      properties:
        branchesChangedIn:
          items:
            type: string
          type: array
        branchesCreatedIn:
          items:
            type: string
          type: array
        createdAt:
          format: date-time
          type: string
        defaultSortKey:
          type: string
        deleted:
          type: boolean
        formulaTemplates:
          type: object
        formulas:
          additionalProperties:
            type: string
          type: object
        id:
          type: string
        links:
          $ref: '#/components/schemas/EntityLinksDto'
        type:
          type: string
        uniqueEntityNumber:
          type: number
        updatedAt:
          format: date-time
          type: string
        values:
          type: object
      required:
        - id
        - values
        - formulas
        - formulaTemplates
        - links
      type: object
    DiagramAnnotationItemDto:
      properties:
        color:
          description: Text color — defaults to "black"
          type: string
        id:
          description: Unique ID (used only for de-duplication)
          type: string
        size:
          description: Font size style — defaults to "l"
          enum:
            - s
            - m
            - l
            - xl
          type: string
        text:
          description: Annotation text
          type: string
        x:
          description: Canvas x position — auto-placed above the diagram if omitted
          type: number
        'y':
          description: Canvas y position — auto-placed above the diagram if omitted
          type: number
      required:
        - id
        - text
      type: object
    DiagramConnectionItemDto:
      properties:
        color:
          description: Arrow color (e.g. "black", "blue") — defaults to "black"
          type: string
        dash:
          description: Arrow dash style — defaults to "draw"
          enum:
            - draw
            - solid
            - dashed
            - dotted
          type: string
        from:
          description: Source entity or node ID
          type: string
        kind:
          description: >-
            Arrow routing style: "elbow" (default) uses right-angle corners,
            "arc" a smooth curve
          enum:
            - arc
            - elbow
          type: string
        label:
          description: Short label shown at the midpoint of the arrow
          type: string
        to:
          description: Target entity or node ID
          type: string
      required:
        - from
        - to
      type: object
    DiagramEntityItemDto:
      properties:
        childColumns:
          description: >-
            When this entity is a container (other items name it as their
            parentId), the fixed number of columns to arrange its children into
            (≥ 1). Omit for an automatic ≈√n grid.
          type: number
        geo:
          description: >-
            Visual treatment of the card. 'pill' renders a compact single-row
            oval (the clean affordance for interfaces and other entities mounted
            on a connection); omit or 'card' for the default header + body card.
          enum:
            - card
            - pill
          type: string
        id:
          description: Platform entity ID of the Flow entity to render
          type: string
        name:
          description: Display name shown on the card
          type: string
        parentId:
          description: >-
            Id of another entity/node in this payload that should contain this
            card. When set, the card is nested inside that container and
            auto-placed in its grid. Omit for a top-level card.
          type: string
        type:
          description: Entity type label (e.g. "Requirement")
          type: string
      required:
        - id
        - name
        - type
      type: object
    DiagramNodeItemDto:
      properties:
        childColumns:
          description: >-
            When this node is a container, the fixed number of columns to
            arrange its children into (≥ 1). Omit for an automatic ≈√n grid.
          type: number
        color:
          description: >-
            tldraw color style (e.g. "black", "blue", "red", "green", "orange",
            "violet") — defaults to "black"
          type: string
        dash:
          description: Border dash style — defaults to "draw"
          enum:
            - draw
            - solid
            - dashed
            - dotted
          type: string
        fill:
          description: Fill style — defaults to "none"
          enum:
            - none
            - semi
            - solid
            - pattern
          type: string
        h:
          description: Height override in pixels (≥ 1)
          type: number
        id:
          description: Unique ID for this node — referenced by connections
          type: string
        name:
          description: Label displayed inside the shape
          type: string
        parentId:
          description: >-
            Id of another node/entity in this payload that should contain this
            node. When set, x/y are ignored and the node is auto-placed inside
            the container.
          type: string
        shape:
          description: Geometric shape type — defaults to "rectangle"
          enum:
            - rectangle
            - ellipse
            - diamond
            - triangle
            - star
            - cloud
          type: string
        size:
          description: Size style controlling font/stroke scale — defaults to "m"
          enum:
            - s
            - m
            - l
            - xl
          type: string
        w:
          description: Width override in pixels (≥ 1)
          type: number
        x:
          description: Canvas x position — auto-placed in a grid when omitted
          type: number
        'y':
          description: Canvas y position — auto-placed in a grid when omitted
          type: number
      required:
        - id
        - name
      type: object
    DiagramSnapshotDto:
      properties:
        schema:
          description: Serialized tldraw schema (versioning metadata)
          type: object
        store:
          description: tldraw store records keyed by record ID
          type: object
      required:
        - store
        - schema
      type: object
    EntityLinksDto:
      properties:
        crosslinks:
          items:
            type: string
          type: array
        inbound:
          items:
            type: string
          type: array
        inboundOrder:
          additionalProperties:
            type: string
          type: object
        inboundTypes:
          additionalProperties:
            type: string
          type: object
        outbound:
          items:
            type: string
          type: array
        outboundOrder:
          additionalProperties:
            type: string
          type: object
        outboundTypes:
          additionalProperties:
            type: string
          type: object
        rootPlaced:
          type: boolean
      required:
        - inbound
        - outbound
        - crosslinks
        - inboundOrder
      type: object
  securitySchemes:
    api-key:
      in: header
      name: X-API-Key
      type: apiKey
    bearer:
      bearerFormat: JWT
      scheme: bearer
      type: http

````