Docs
Schedule demo Open app

Eraser DSL → Diagram

POST https://app.eraser.io/api/render/elements

This endpoint creates a diagram from user-provided Eraser DSL (diagram-as-code).

Note: This endpoint does not use AI, it simply generates a diagram from the Eraser DSL (diagram-as-code) provided by the user. To learn more about the Eraser DSL, see our docs. If you are looking for the AI diagram endpoint, see here .

The diagram code must be placed in the code field of each element, with all line breaks and special characters properly escaped. The simplest way to prepare your Eraser DSL code is to open your browser's JavaScript console and run JSON.stringify(YOUR-ERASER-DSL).replaceAll('\\n', '\n'), then use the escaped output in your request.

curl --location 'https://app.eraser.io/api/render/elements' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "theme": "dark",
    "background": true,
    "elements": [
        {
            "type": "diagram",
            "diagramType": "sequence-diagram",
            "code": "Client [icon: monitor, color: gray]\nServer [icon: server, color: blue]\nService [icon: tool, color: green]\n\nClient > Server: Data request\nactivate Server\nServer <> Service: Service request\n\nloop [label: until success, color: green] {\n  Service > Service: Check availability\n}\n\nServer - Service: Data processing\nServer --> Client: Data response\ndeactivate Server"
        }
    ]
}'

To render a freeform diagram, set diagramType to freeform-diagram and pass a freeformElements array instead of code:

curl --location 'https://app.eraser.io/api/render/elements' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "theme": "dark",
    "elements": [
        {
            "type": "diagram",
            "diagramType": "freeform-diagram",
            "freeformElements": [
                { "id": "a", "tag": "Shape", "x": 0, "y": 0, "texts": [{ "text": "User Service" }] },
                { "id": "b", "tag": "Shape", "x": 300, "y": 0, "texts": [{ "text": "Payment Service" }] },
                { "id": "r1", "tag": "Relationship", "from": "a", "to": "b", "label": "calls" }
            ]
        }
    ]
}'

An example response is:

{
    "imageUrl": "https://IMAGE-SITE-URL/IMAGE-NAME.png",
    "createEraserFileUrl": "https://ERASER-URL-TO-OPEN-DIAGRAM-IN-EDITOR"
}

Request body

elements object[] required12 fields

Eraser canvas element objects
type string required

Select element type. Use 'diagram' to generate a diagram

diagramType string required

Select one of the supported diagram types. DSL types (sequence-diagram, entity-relationship-diagram, cloud-architecture-diagram, flowchart-diagram, bpmn-diagram) require the 'code' field. 'freeform-diagram' is element-based and requires 'freeformElements' instead of 'code'.

  • sequence-diagram
  • entity-relationship-diagram
  • cloud-architecture-diagram
  • flowchart-diagram
  • bpmn-diagram
  • freeform-diagram
code string

Valid Eraser DSL code that describes the diagram. Required for all DSL diagram types; omit for 'freeform-diagram'.

freeformElements object[] 8 fields

Freeform diagram elements, used instead of 'code' when diagramType is 'freeform-diagram'. Required for freeform diagrams. Coordinates are diagram-local (top-left origin).
id string required

Unique element identifier. Relationships reference elements by this id.

tag string required

The kind of freeform element.

  • Shape
  • Icon
  • DatabaseTable
  • Textbox
  • Group
  • Lane
  • Pool
  • Border
  • Legend
  • Relationship
  • DatabaseRelationship
x number

X position in diagram-local coordinates. Not used by relationship tags.

y number

Y position in diagram-local coordinates. Not used by relationship tags.

width number

Optional width.

height number

Optional height.

from string

Relationship tags only: id of the source element.

to string

Relationship tags only: id of the target element.

background boolean

Select transparent (false) or solid (true) background. Defaults to false.

theme string

Select "light" or "dark" theme. Defaults to "light".

  • light
  • dark
imageQuality integer

Image quality/resolution multiplier. Use 1 (low), 2 (medium), or 3 (high). Defaults to 2.

  • 1
  • 2
  • 3
scale integer

Deprecated. Use imageQuality instead.

  • 1
  • 2
  • 3
returnImageAsFile boolean

When true, returns the image as a file stream instead of a URL.

returnFile boolean

Deprecated. Use returnImageAsFile instead.

fileOptions object 2 fields

Options for creating an Eraser file immediately with granular link access settings, rather than returning a URL for manual creation.
create boolean

When true, creates an Eraser file immediately instead of returning a URL to create one later.

linkAccess string

Link access setting for the created Eraser file. Only applies when `create` is true. See https://docs.eraser.io/sharing-a-file for more information. Note: "sso-readable" and "sso-editable" only work for teams that have SSO enabled. Using them without SSO configured may cause errors or unexpected access behavior.

  • no-link-access
  • anyone-with-link-can-edit
  • publicly-viewable
  • publicly-editable
  • sso-readable
  • sso-editable
title string

Title for the created Eraser file. Only applies when `fileOptions.create` is true. If not provided, title is derived from the diagram code.

Responses

200 – The result of the diagram generation

imageUrl string

URL of the generated diagram as a PNG image

createEraserFileUrl string

URL to create an Eraser file to edit the generated diagram. Not returned when `fileOptions.create` is `true`.

fileUrl string

URL to the created Eraser file. Only returned when `fileOptions.create` is `true`.

200 response 
{
  "imageUrl": "string",
  "createEraserFileUrl": "string",
  "fileUrl": "string"
}

400 – The request is missing the 'elements' parameter or validation failed

403 – Unauthorized

500 – Eraser was unable to generate a result

503 – Service temporarily unavailable. This may be the result of too many requests.