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.

To write into a file that already exists, set fileOptions.targetFileId. Add fileOptions.targetDiagramId to edit one of that file's diagrams in place rather than adding new ones. Both require a token with the file:write scope, and neither can be combined with fileOptions.create. The response returns fileUrl and the saved diagrams[], each carrying the id you need to edit or export it later.

Writing into a file does not render an image unless you ask for one with includeImage: true. To get an image of a diagram that is already stored, use POST /api/export/diagram.

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."
}'

An example cURL request for generating into an existing file:

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
  "text": "Add a Redis cache between the API and the database.",
  "diagramType": "cloud-architecture-diagram",
  "fileOptions": {
    "targetFileId": "abc123"
  }
}'

An example cURL request for editing a diagram in that file in place, asking for an image of the result:

curl --location 'https://app.eraser.io/api/render/prompt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
  "text": "Put a CDN in front of the load balancer.",
  "includeImage": true,
  "fileOptions": {
    "targetFileId": "abc123",
    "targetDiagramId": "def456"
  }
}'

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"
    }
  ]
}

An example response when fileOptions.targetFileId is set. No imageUrl, because includeImage defaults to false on this path:

{
  "requestId": "generated-request-id",
  "fileUrl": "https://app.eraser.io/workspace/abc123",
  "diagrams": [
    {
      "id": "def456",
      "diagramUrl": "https://app.eraser.io/workspace/abc123?diagram=def456&layout=canvas",
      "diagramType": "cloud-architecture-diagram",
      "code": "// EXAMPLE DIAGRAM \n A > B \n B > C",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

An example response when fileOptions.targetDiagramId is set. changed reports whether the edit altered the diagram:

{
  "requestId": "generated-request-id",
  "fileUrl": "https://app.eraser.io/workspace/abc123",
  "changed": true,
  "imageUrl": "https://IMAGE-SITE-URL/IMAGE-NAME.png",
  "diagrams": [
    {
      "id": "def456",
      "diagramUrl": "https://app.eraser.io/workspace/abc123?diagram=def456&layout=canvas",
      "diagramType": "cloud-architecture-diagram",
      "code": "// EDITED DIAGRAM \n A > CDN \n CDN > B \n B > C",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

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.

includeImage boolean

Whether to render an image of the result. Defaults to true, except when generating into an existing file (`fileOptions.targetFileId`), where it defaults to false. When false, no image is rendered or stored and `imageUrl` is absent; `background`, `theme`, and `imageQuality` are ignored, and `returnImageAsFile` cannot be used.

fileOptions object 4 fields

Where the generated diagrams go. Use `create` to make a new Eraser file, or `targetFileId` to write into one that already exists. The two are mutually exclusive, and `targetFileId` requires a token with the `file:write` scope.

create boolean

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

targetFileId string

ID of an existing file to generate into. The diagrams are saved to that file and returned in `diagrams[]` with their IDs. Cannot be combined with `create` or `returnImageAsFile`.

targetDiagramId string

ID of a diagram within `targetFileId` to edit in place, instead of adding new diagrams to the file. Requires `targetFileId`.

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 an image. Only returned when an image was rendered – see `includeImage`.

imageError string

Why the image could not be rendered. Only returned when an image was requested and rendering it failed. When generating into a file, the diagrams are still saved and returned.

createEraserFileUrl string

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

fileUrl string

URL to the Eraser file holding the diagrams. Returned when `fileOptions.create` or `fileOptions.targetFileId` is set.

diagrams object[] 6 fields

The generated diagrams. When writing into a file (`fileOptions.targetFileId`), these are the diagrams as saved, and each carries its ID.

id string

ID of the saved diagram. Only returned when `fileOptions.targetFileId` is set. Pass it to `POST /api/export/diagram` or back as `fileOptions.targetDiagramId` to edit it.

diagramUrl string

URL to view the diagram in the Eraser canvas. Only returned when `fileOptions.targetFileId` is set.

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

diagramTitle string

Title the model gave the diagram, when it produced one.

updatedAt string

ISO 8601 timestamp of when the diagram was last updated. Only returned when `fileOptions.targetFileId` is set.

changed boolean

Whether the edit altered the diagram. Only returned when `fileOptions.targetDiagramId` is set; false when the model declined the edit or produced identical output.

relevantFilePaths string[]

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

warning string

Present when part of the result could not be saved – for example a model output holding more than one freeform diagram, of which only the first is persisted.

200 response

{
  "requestId": "string",
  "imageUrl": "string",
  "imageError": "string",
  "createEraserFileUrl": "string",
  "fileUrl": "string",
  "diagrams": [
    {
      "id": "string",
      "diagramUrl": "string",
      "diagramType": "sequence-diagram",
      "code": "string",
      "diagramTitle": "string",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "changed": true,
  "relevantFilePaths": "string",
  "warning": "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.