Prompt → Diagram (AI)

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

This endpoint generates a new AI diagram or edits an existing one from user-provided input, with support for file attachments and additional context.

Example requests

An example cURL request for generating a new diagram:

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "theme": "dark",
    "diagramType": "cloud-architecture-diagram",
    "text": "Azure Front Door routes to a web UI (App Service/Static Web Apps); requests go through API Management to Cognitive Search (indexing Blob Storage/DevOps Repos) and Azure OpenAI for answers; Functions handle transforms, Redis caches; responses return via API Management; monitored with Azure Monitor + Application Insights."
}'

An example cURL request for editing an existing diagram:

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "priorRequestId": "6ZoBxeDf94ix9IB7Fx8G",
    "text": "Add a CDN layer in front of the Azure Front Door"
}'

An example cURL request with a file attachment:

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "text": "Generate a diagram based on this screenshot",
    "attachments": [
        {
            "filename": "screenshot.png",
            "mimeType": "image/png",
            "content": "$BASE64-ENCODED-CONTENT-HERE"
        }
    ]
}'

Here's an example cURL request using a git repository:

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
  "text": "Generate an architecture diagram based on Terraform files in /wordpress-fargate/.",
  "diagramType": "cloud-architecture-diagram",
  "gitContexts": [
    {
      "orgName": "acme-corp",
      "repoName": "terraform-iac"
    }
  ]
}'

An example cURL request using a preset library (contextId can be found on the AI Presets page; docs):

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "text": "Create a mobile application architecture diagram utilizing the Payment Processing Module and Authentication Module from the ACME Corp Architecture Library.",
    "diagramType": "cloud-architecture-diagram",
    "contextId": "$CONTEXT-ID"
}'

An example cURL requesting an editable Eraser file with granular link access options:

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
  "diagramType": "cloud-architecture-diagram",
  "fileOptions": {
    "create": true,
    "linkAccess": "publicly-editable"  
  },
  "text": "3-tier web application architecture using Azure."
}'

Example responses

An example response is:

{
  "requestId": "generated-request-id",
  "imageUrl": "https://IMAGE-SITE-URL/IMAGE-NAME.png",
  "createEraserFileUrl": "https://ERASER-URL-TO-OPEN-DIAGRAM-IN-EDITOR",
  "diagrams": [
    {
      "diagramType": "cloud-architecture-diagram",
      "code": "// EXAMPLE DIAGRAM \n A > B \n B > C"
    }
  ]
}

An example response when fileOptions.create is set to true

{
  "requestId": "generated-request-id",
  "imageUrl": "https://IMAGE-SITE-URL/IMAGE-NAME.png",
  "fileUrl": "https://ERASER-URL-TO-OPEN-DIAGRAM-IN-EDITOR",
  "diagrams": [
    {
      "diagramType": "cloud-architecture-diagram",
      "code": "// EXAMPLE DIAGRAM \n A > B \n B > C"
    }
  ]
}

Request body

text string required

The prompt. The input code or natural language which describes a diagram.

diagramType string

Select desired diagram type. Will automatically detect diagram type when unspecified. Note: "freeform-diagram" is element-based – it cannot be edited via inlineCodeEdit (use priorRequestId instead), and its responses do not include a "code" field.

sequence-diagram
entity-relationship-diagram
cloud-architecture-diagram
flowchart-diagram
bpmn-diagram
freeform-diagram

mode string

Model tier. "premium" (default) uses a higher-quality model; "standard" uses a faster, lower-cost model. Defaults to "premium".

standard
premium

priorRequestId string

ID of a previous request to edit. When provided, the API will edit the diagram from that request.

attachments object[] 3 fields

File attachments to provide context for diagram generation. Accepts PNG, JPEG, and PDF files.

filename string required

Name of the file

mimeType string required

MIME type of the file (e.g., image/png, image/jpeg, file/pdf)

content string required

Base64-encoded file content (max 10MB)

contextId string

ID of an AI preset to use as context for generation. Find contextId in the AI preset page (https://app.eraser.io/dashboard/ai-preset).

templateId string

ID (workspaceId) of a template within a preset. Both contextId and templateId are required to use a template. Find ID by navigating to AI preset (https://app.eraser.io/dashboard/ai-preset) > Templates > Open a template

inlineCodeEdit object 2 fields

Edit flow without a prior AI request: pass existing canvas diagram code and type directly. Mutually exclusive with priorRequestId for the edit source.

code string required

The existing Eraser DSL code of the diagram to edit

diagramType string required

Diagram type of the existing code

sequence-diagram
entity-relationship-diagram
cloud-architecture-diagram
flowchart-diagram
bpmn-diagram

git object 3 fields

Deprecated. Use gitContexts instead.

repoName string

Name of the repository

orgName string

Name of the organization or owner

publicRepoUrl string

Full URL of a public GitHub repository (e.g., https://github.com/org/repo)

gitContexts object[]

Git repository contexts for diagram generation. Supports one or more repositories. Use publicRepoUrl for public repos, or repoName and orgName for private repos connected to your team.

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

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.

scale integer

Deprecated. Use imageQuality instead.

Responses

200 – The result of the diagram generation

requestId string

ID of the diagram generation request

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`.

diagrams object[] 2 fields

Array of generated Eraser DSL code for the diagram

diagramType string

Type of the generated diagram. For "freeform-diagram", the "code" field is omitted.

sequence-diagram
entity-relationship-diagram
cloud-architecture-diagram
flowchart-diagram
bpmn-diagram
freeform-diagram

code string

The generated Eraser DSL code for the diagram

relevantFilePaths string[]

File paths from the Git repository context used to generate the diagram. Only returned when gitContexts is provided. Format: orgName/repoName:filePath

200 response

{
  "requestId": "string",
  "imageUrl": "string",
  "createEraserFileUrl": "string",
  "fileUrl": "string",
  "diagrams": [
    {
      "diagramType": "sequence-diagram",
      "code": "string"
    }
  ],
  "relevantFilePaths": "string"
}

Prompt → Diagram (AI)

Example requests

Example responses

Request body

Responses

200 – The result of the diagram generation

400 – The request is missing required parameters or validation failed

403 – Unauthorized

404 – Prior request or context not found

500 – Eraser was unable to generate a result

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