openapi: 3.0.3
info:
  title: Eraser AI Requests Diagrams (AI) API
  description: The Eraser REST API provides programmatic access to diagram generation, file management, folder management, audit logs, and team usage metrics. Developers can generate diagrams from natural language prompts or Eraser DSL, create and manage files and diagrams on the canvas, and retrieve aggregated usage metrics. API access requires a team API token and is available on Starter, Business, and Enterprise paid plans with usage-based billing for API calls beyond plan credits.
  version: v1.0
  contact:
    name: Eraser Support
    url: https://www.eraser.io/
    email: hello@eraser.io
  termsOfService: https://www.eraser.io/
servers:
- url: https://app.eraser.io
  description: Eraser API Server
security:
- bearerAuth: []
tags:
- name: Diagrams (AI)
  description: Generate diagrams from natural language prompts or Eraser DSL using AI
paths:
  /api/render/prompt:
    post:
      operationId: generateDiagramFromPrompt
      summary: Generate diagram from natural language prompt (AI)
      description: Generates a diagram from natural language or code input using AI. Supports a wide range of diagram types including flow charts, ERDs, sequence diagrams, cloud architecture diagrams, and BPMN diagrams.
      tags:
      - Diagrams (AI)
      externalDocs:
        description: API documentation for DiagramGPT
        url: https://docs.eraser.io/reference/generate-diagram-from-prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateFromPromptRequest'
      responses:
        '200':
          description: Diagram generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateFromPromptResponse'
        '400':
          description: Missing required parameters or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Prior request or context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Generation unable to complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable or rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/render/elements:
    post:
      operationId: generateDiagramFromEraserDsl
      summary: Generate diagram from Eraser DSL code
      description: Generates a diagram image from Eraser DSL canvas elements. Use this endpoint when you have structured DSL code and want to render it into a PNG image or create an editable Eraser file.
      tags:
      - Diagrams (AI)
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/generate-diagram-from-eraser-dsl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateFromDslRequest'
      responses:
        '200':
          description: Diagram rendered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateFromDslResponse'
        '400':
          description: Missing elements parameter or validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Generation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DslElement:
      type: object
      required:
      - type
      - diagramType
      properties:
        type:
          type: string
          enum:
          - diagram
          description: Element type (must be 'diagram')
        diagramType:
          $ref: '#/components/schemas/DiagramTypeWithFreeform'
        code:
          type: string
          description: Eraser DSL code (required for all types except freeform-diagram)
        freeformElements:
          type: array
          items:
            type: object
          description: Array of element objects (required for freeform-diagram only)
    GenerateFromPromptResponse:
      type: object
      properties:
        requestId:
          type: string
          description: Diagram generation request ID
        imageUrl:
          type: string
          description: URL of the generated diagram as a PNG image
        createEraserFileUrl:
          type: string
          description: URL to create an editable file (when fileOptions.create is false)
        fileUrl:
          type: string
          description: Direct editable file URL (when fileOptions.create is true)
        diagrams:
          type: array
          items:
            $ref: '#/components/schemas/GeneratedDiagram'
          description: Generated Eraser DSL code objects
        relevantFilePaths:
          type: array
          items:
            type: string
          description: File paths from Git context (when gitContexts provided)
    GitContext:
      type: object
      properties:
        url:
          type: string
          description: Public Git repository URL
        repository:
          type: string
          description: Private repository name
        organization:
          type: string
          description: Organization name for private repositories
    GenerateFromPromptRequest:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          description: Natural language or code describing the diagram
        diagramType:
          $ref: '#/components/schemas/DiagramTypeWithFreeform'
        mode:
          type: string
          enum:
          - standard
          - premium
          default: premium
          description: AI model tier to use
        priorRequestId:
          type: string
          description: ID of a previous request to edit an existing diagram (mutually exclusive with inlineCodeEdit)
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/FileAttachment'
          description: File attachments (PNG, JPEG, PDF)
        contextId:
          type: string
          description: AI preset ID for generation context
        templateId:
          type: string
          description: Template ID within a preset (requires contextId)
        inlineCodeEdit:
          $ref: '#/components/schemas/InlineCodeEdit'
        gitContexts:
          type: array
          items:
            $ref: '#/components/schemas/GitContext'
          description: Git repositories to use as context
        returnImageAsFile:
          type: boolean
          description: Return image as file stream instead of URL
        fileOptions:
          $ref: '#/components/schemas/FileOptions'
        background:
          type: boolean
          description: Transparent (false) or solid (true) background
        theme:
          type: string
          enum:
          - light
          - dark
          default: light
          description: Diagram color theme
        imageQuality:
          type: integer
          enum:
          - 1
          - 2
          - 3
          default: 2
          description: Resolution multiplier (1=low, 2=medium, 3=high)
    FileOptions:
      type: object
      properties:
        create:
          type: boolean
          description: Whether to create an Eraser file from the generated diagram
        linkAccess:
          $ref: '#/components/schemas/LinkAccess'
    LinkAccess:
      type: string
      enum:
      - no-link-access
      - anyone-with-link-can-edit
      - publicly-viewable
      - publicly-editable
      - sso-readable
      - sso-editable
      description: File link access permission level
    GenerateFromDslResponse:
      type: object
      properties:
        imageUrl:
          type: string
          description: URL of the generated PNG diagram image
        createEraserFileUrl:
          type: string
          description: URL to create an editable Eraser file (omitted if fileOptions.create is true)
        fileUrl:
          type: string
          description: URL to created Eraser file (returned only when fileOptions.create is true)
    GeneratedDiagram:
      type: object
      properties:
        diagramType:
          $ref: '#/components/schemas/DiagramTypeWithFreeform'
        code:
          type: string
          description: Generated Eraser DSL code
    InlineCodeEdit:
      type: object
      required:
      - code
      - diagramType
      properties:
        code:
          type: string
          description: Existing diagram code to edit
        diagramType:
          $ref: '#/components/schemas/DiagramTypeWithFreeform'
    DiagramTypeWithFreeform:
      type: string
      enum:
      - sequence-diagram
      - entity-relationship-diagram
      - cloud-architecture-diagram
      - flowchart-diagram
      - bpmn-diagram
      - freeform-diagram
      description: Type of Eraser diagram (including freeform)
    FileAttachment:
      type: object
      required:
      - filename
      - mimeType
      - content
      properties:
        filename:
          type: string
          description: Name of the attached file
        mimeType:
          type: string
          enum:
          - image/png
          - image/jpeg
          - application/pdf
          description: MIME type of the attachment
        content:
          type: string
          description: Base64-encoded file content
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
    GenerateFromDslRequest:
      type: object
      required:
      - elements
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/DslElement'
          description: Eraser canvas element objects defining the diagram
        background:
          type: boolean
          description: Transparent (false) or solid (true) background. Defaults to false.
        theme:
          type: string
          enum:
          - light
          - dark
          default: light
          description: Diagram color theme
        imageQuality:
          type: integer
          enum:
          - 1
          - 2
          - 3
          default: 2
          description: Resolution multiplier (1=low, 2=medium, 3=high)
        returnImageAsFile:
          type: boolean
          description: Return image as file stream instead of URL
        fileOptions:
          $ref: '#/components/schemas/FileOptions'
        title:
          type: string
          description: Title for the created Eraser file (when fileOptions.create is true)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Team-specific API bearer token from Eraser settings
    auditApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Audit-specific API key for accessing audit log endpoints
externalDocs:
  description: Eraser API Documentation
  url: https://docs.eraser.io/docs/eraser-api