openapi: 3.0.3
info:
  title: Eraser 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/
externalDocs:
  description: Eraser API Documentation
  url: https://docs.eraser.io/docs/eraser-api
servers:
  - url: https://app.eraser.io
    description: Eraser API Server
tags:
  - name: Diagrams (AI)
    description: Generate diagrams from natural language prompts or Eraser DSL using AI
  - name: AI Requests
    description: Retrieve previously generated AI diagram requests
  - name: Files
    description: Create and manage Eraser files
  - name: Diagram Elements
    description: Manage diagram elements within files
  - name: Folders
    description: Create and manage folders for organizing files
  - name: Audit Logs
    description: Query audit events for compliance and monitoring
  - name: Usage Metrics
    description: Retrieve team usage and activity metrics
security:
  - bearerAuth: []
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'

  /api/ai-requests/{requestId}:
    get:
      operationId: retrieveAiRequest
      summary: Retrieve a previous AI diagram request
      description: >-
        Retrieves the inputs and outputs of a previously generated AI diagram
        request by its request ID. Optionally returns the PNG image directly
        as a file stream.
      tags:
        - AI Requests
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/retrieve-ai-request
      parameters:
        - name: requestId
          in: path
          required: true
          description: ID of the AI request to retrieve (from /api/render/prompt response)
          schema:
            type: string
        - name: returnFile
          in: query
          required: false
          description: When true, returns the PNG image file directly instead of JSON
          schema:
            type: string
            enum: ['true', 'false']
      responses:
        '200':
          description: AI request retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiRequest'
            image/png:
              schema:
                type: string
                format: binary
                description: PNG image file (when returnFile=true)
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: AI request not found or PNG unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/files:
    post:
      operationId: createFile
      summary: Create a new file
      description: Creates a new Eraser file with optional document content and canvas elements.
      tags:
        - Files
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/create-file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileRequest'
      responses:
        '200':
          description: File created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileWithContent'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listFiles
      summary: List files
      description: >-
        Returns a paginated list of files for the authenticated team, with
        optional filtering by folder, author, and sorting.
      tags:
        - Files
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/list-files
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum number of files to return (1-500). Defaults to 100.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: cursor
          in: query
          required: false
          description: Cursor for pagination. Use nextCursor from a previous response.
          schema:
            type: string
        - name: folderId
          in: query
          required: false
          description: Filter files by folder ID.
          schema:
            type: string
        - name: sort
          in: query
          required: false
          description: Sort field with optional - prefix for descending order. Defaults to -updatedAt.
          schema:
            type: string
            enum:
              - createdAt
              - '-createdAt'
              - updatedAt
              - '-updatedAt'
            default: '-updatedAt'
        - name: author
          in: query
          required: false
          description: Filter by author (user ID or email address).
          schema:
            type: string
      responses:
        '200':
          description: Files retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileList'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/files/{fileId}:
    get:
      operationId: getFile
      summary: Get a file
      description: Retrieves a specific file by ID, including its content and canvas elements.
      tags:
        - Files
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/get-file
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file to retrieve
          schema:
            type: string
      responses:
        '200':
          description: File retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileWithContent'
        '400':
          description: Invalid file ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found, private, archived, template, or belongs to different team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateFile
      summary: Update a file
      description: >-
        Updates a file's title, folder location, or document content. Markdown
        diagram code blocks in the document are converted to embedded diagrams.
      tags:
        - Files
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/update-file
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFileRequest'
      responses:
        '200':
          description: File updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileWithContent'
        '400':
          description: Invalid file ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found, private, archived, template, or belongs to different team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: archiveFile
      summary: Archive a file
      description: >-
        Archives (soft-deletes) a file by ID. The file can be restored through
        the Eraser UI afterward.
      tags:
        - Files
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/archive-file
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file to archive
          schema:
            type: string
      responses:
        '200':
          description: File archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveFileResponse'
        '400':
          description: Invalid file ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found, private, archived, template, or belongs to different team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/files/{fileId}/diagrams:
    post:
      operationId: createDiagram
      summary: Create a diagram in a file
      description: Creates a new diagram element within an existing file.
      tags:
        - Diagram Elements
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/create-diagram
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file to add the diagram to
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDiagramRequest'
      responses:
        '200':
          description: Diagram created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Diagram'
        '400':
          description: Invalid file ID or missing diagramType
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found, private, archived, template, or belongs to different team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listDiagrams
      summary: List diagrams in a file
      description: Returns all diagram elements within a specific file.
      tags:
        - Diagram Elements
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/list-diagrams
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file containing the diagrams
          schema:
            type: string
      responses:
        '200':
          description: Diagrams retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Diagram'
        '400':
          description: Invalid file ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found, private, archived, template, or belongs to different team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/files/{fileId}/diagrams/{diagramId}:
    get:
      operationId: getDiagram
      summary: Get a diagram
      description: Retrieves a specific diagram element from a file by its ID.
      tags:
        - Diagram Elements
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/get-diagram
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file containing the diagram
          schema:
            type: string
        - name: diagramId
          in: path
          required: true
          description: ID of the diagram to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Diagram retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Diagram'
        '400':
          description: Invalid file ID or diagram ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File or diagram not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateDiagram
      summary: Update a diagram
      description: Updates the DSL code of an existing diagram element within a file.
      tags:
        - Diagram Elements
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/update-diagram
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file containing the diagram
          schema:
            type: string
        - name: diagramId
          in: path
          required: true
          description: ID of the diagram to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDiagramRequest'
      responses:
        '200':
          description: Diagram updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Diagram'
        '400':
          description: Invalid file/diagram ID or missing code field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File or diagram not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteDiagram
      summary: Delete a diagram
      description: Permanently deletes a diagram element from a file.
      tags:
        - Diagram Elements
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/delete-diagram
      parameters:
        - name: fileId
          in: path
          required: true
          description: ID of the file containing the diagram
          schema:
            type: string
        - name: diagramId
          in: path
          required: true
          description: ID of the diagram to delete
          schema:
            type: string
      responses:
        '200':
          description: Diagram deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDiagramResponse'
        '400':
          description: Invalid file ID or diagram ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File or diagram not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/folders:
    post:
      operationId: createFolder
      summary: Create a folder
      description: Creates a new folder for organizing Eraser files.
      tags:
        - Folders
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/create-folder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderRequest'
      responses:
        '200':
          description: Folder created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFolderResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listFolders
      summary: List folders
      description: >-
        Returns folders for the authenticated team. Optionally filter by
        parent folder or include all descendants recursively.
      tags:
        - Folders
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/list-folders
      parameters:
        - name: parentFolderId
          in: query
          required: false
          description: Parent folder to list children of. Defaults to null (root folders).
          schema:
            type: string
        - name: recursive
          in: query
          required: false
          description: Include all descendant folders. Defaults to false.
          schema:
            type: string
            enum: ['true', 'false']
      responses:
        '200':
          description: Folders retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Folder'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/folders/{folderId}:
    get:
      operationId: getFolder
      summary: Get a folder
      description: Retrieves a specific folder by its ID.
      tags:
        - Folders
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/get-folder
      parameters:
        - name: folderId
          in: path
          required: true
          description: Unique folder identifier
          schema:
            type: string
      responses:
        '200':
          description: Folder retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          description: Invalid folder ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateFolder
      summary: Update a folder
      description: Updates the name or parent folder of an existing folder.
      tags:
        - Folders
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/update-folder
      parameters:
        - name: folderId
          in: path
          required: true
          description: The folder identifier to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFolderRequest'
      responses:
        '200':
          description: Folder updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid folder ID or request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteFolder
      summary: Delete a folder
      description: >-
        Deletes a folder. Optionally deletes all child folders and archives
        their files recursively.
      tags:
        - Folders
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/delete-folder
      parameters:
        - name: folderId
          in: path
          required: true
          description: The folder identifier to delete
          schema:
            type: string
        - name: recursive
          in: query
          required: false
          description: Deletes all child folders and archives their workspaces. Defaults to false.
          schema:
            type: string
            enum: ['true', 'false']
      responses:
        '200':
          description: Folder deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid folder ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/audit-logs:
    get:
      operationId: getAuditLogs
      summary: Query audit logs
      description: >-
        Query audit events with cursor-based pagination. Requires an audit API
        key (not the team bearer token). Supports filtering by time range,
        event type, and user.
      tags:
        - Audit Logs
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/get-audit-logs
      security:
        - auditApiKey: []
      parameters:
        - name: startTime
          in: query
          required: false
          description: Start of the time range (inclusive). RFC3339/ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          required: false
          description: End of the time range (exclusive). RFC3339/ISO 8601 timestamp.
          schema:
            type: string
            format: date-time
        - name: cursor
          in: query
          required: false
          description: Opaque cursor string for pagination.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum events per request (1-1000). Defaults to 100.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: eventType
          in: query
          required: false
          description: Filter by action type.
          schema:
            type: string
            enum:
              - auth.login
              - auth.logout
              - iam.user.created
              - iam.user.deleted
              - iam.user.invited
              - iam.role.granted
              - iam.role.revoked
              - admin.api_key.created
              - admin.api_key.deleted
              - admin.settings.changed
              - admin.integration.connected
              - admin.integration.disconnected
              - admin.team.created
              - admin.team.deleted
              - data.file.created
              - data.file.archived
              - data.file.deleted
              - data.file.exported
              - data.file.invite_sent
              - data.file.visited
              - data.file.settings.changed
        - name: userId
          in: query
          required: false
          description: Filter events by the ID of the user who performed the action.
          schema:
            type: string
        - name: format
          in: query
          required: false
          description: Output format. Defaults to ecs.
          schema:
            type: string
            enum:
              - ecs
              - splunk
            default: ecs
      responses:
        '200':
          description: Audit events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing audit API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Audit logging not configured for deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/reports/usage:
    get:
      operationId: getUsageMetrics
      summary: Get team usage metrics
      description: >-
        Retrieves aggregated usage metrics for the team, including active
        members, file counts, and AI credit usage over a configurable date range.
      tags:
        - Usage Metrics
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/get-usage-metrics
      parameters:
        - name: rangeDays
          in: query
          required: false
          description: Number of days to include in the report. Defaults to 30, min 1, max 365.
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
        - name: endDate
          in: query
          required: false
          description: End date for the report range (YYYY-MM-DD format).
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Usage metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageMetricsResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized - token is valid but lacks permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  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

  schemas:
    DiagramType:
      type: string
      enum:
        - sequence-diagram
        - entity-relationship-diagram
        - cloud-architecture-diagram
        - flowchart-diagram
        - bpmn-diagram
      description: Type of Eraser diagram

    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)

    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

    CanvasElement:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: Element category (e.g., diagram, rectangle, ellipse)
        diagramType:
          $ref: '#/components/schemas/DiagramType'
        code:
          type: string
          description: Eraser DSL code for diagram rendering
        x:
          type: number
          description: Horizontal canvas position
        y:
          type: number
          description: Vertical canvas position
        width:
          type: number
          description: Element width
        height:
          type: number
          description: Element height

    CanvasElementWithId:
      allOf:
        - $ref: '#/components/schemas/CanvasElement'
        - type: object
          properties:
            id:
              type: string
              description: Unique element identifier

    FileContent:
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/CanvasElementWithId'
          description: Canvas elements in the file
        document:
          type: string
          description: Markdown content of the file's document

    File:
      type: object
      required:
        - id
        - fileUrl
        - title
        - author
        - createdAt
        - updatedAt
        - linkAccess
      properties:
        id:
          type: string
          description: Unique file identifier
        fileUrl:
          type: string
          description: URL to view the file in Eraser
        title:
          type: string
          description: File name
        author:
          type: string
          description: Creator's user ID
        folderId:
          type: string
          nullable: true
          description: Parent folder ID, or null if at root
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 last modification timestamp
        linkAccess:
          $ref: '#/components/schemas/LinkAccess'

    FileWithContent:
      allOf:
        - $ref: '#/components/schemas/File'
        - type: object
          properties:
            content:
              $ref: '#/components/schemas/FileContent'

    FileList:
      type: object
      required:
        - files
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/File'
        nextCursor:
          type: string
          nullable: true
          description: Cursor for retrieving the next page of results

    Diagram:
      type: object
      required:
        - id
        - diagramUrl
        - diagramType
        - code
        - updatedAt
      properties:
        id:
          type: string
          description: Unique diagram identifier
        diagramUrl:
          type: string
          description: Canvas URL for viewing the diagram
        diagramType:
          $ref: '#/components/schemas/DiagramType'
        code:
          type: string
          description: Eraser DSL code for the diagram
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 last modification timestamp

    Folder:
      type: object
      required:
        - id
        - name
        - order
        - teamId
        - createdBy
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: Unique folder identifier
        name:
          type: string
          description: Folder name
        order:
          type: integer
          description: Sort order among sibling folders
        teamId:
          type: string
          description: Team ID
        createdBy:
          type: string
          description: Creator's user ID
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 last updated timestamp
        parentFolderId:
          type: string
          nullable: true
          description: Parent folder ID, or null if root-level

    AuditEventECS:
      type: object
      properties:
        id:
          type: string
          description: Unique event identifier
        '@timestamp':
          type: string
          format: date-time
          description: Event timestamp
        event:
          type: object
          properties:
            id:
              type: string
            category:
              type: string
            action:
              type: string
            outcome:
              type: string
        user:
          type: object
          description: User who performed the action
        user.target:
          type: object
          description: Target user of the action (if applicable)
        organization:
          type: object
          description: Organization context
        url:
          type: object
          description: URL context of the event
        eraser:
          type: object
          properties:
            teamId:
              type: string
            workspaceId:
              type: string
            organizationId:
              type: string
            metadata:
              type: object

    AuditLogResponse:
      type: object
      required:
        - events
        - hasMore
        - serverTime
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/AuditEventECS'
        nextCursor:
          type: string
          nullable: true
          description: Cursor for pagination
        hasMore:
          type: boolean
          description: Whether more events are available
        serverTime:
          type: string
          format: date-time
          description: Current server time

    UsageMemberMetrics:
      type: object
      properties:
        email:
          type: string
          description: Member email address
        displayName:
          type: string
          description: Member display name
        filesCreated:
          type: integer
          description: Number of files created in range
        filesViewed:
          type: integer
          description: Number of unique files viewed in range
        fileViews:
          type: integer
          description: Total file view count in range
        aiCreditsUsed:
          type: integer
          description: AI credits consumed in range
        lastActive:
          type: string
          format: date-time
          description: ISO 8601 timestamp of last activity

    UsageMetricsResponse:
      type: object
      required:
        - range
        - aggregate
        - members
      properties:
        range:
          type: object
          required:
            - start
            - end
          properties:
            start:
              type: string
              format: date
              description: Report range start date
            end:
              type: string
              format: date
              description: Report range end date
        aggregate:
          type: object
          properties:
            teamName:
              type: string
              description: Team name
            totalMembers:
              type: integer
              description: Total team members
            activeMembers:
              type: integer
              description: Members active in the period
            inactiveMembers:
              type: integer
              description: Members inactive in the period
            totalFiles:
              type: integer
              description: Total files in the team
            totalFilesCreated:
              type: integer
              description: Files created in the period
            totalFilesViewed:
              type: integer
              description: Unique files viewed in the period
            totalFileViews:
              type: integer
              description: Total file views in the period
            totalAiCreditsUsed:
              type: integer
              description: Total AI credits used in the period
        members:
          type: array
          items:
            $ref: '#/components/schemas/UsageMemberMetrics'

    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

    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

    FileOptions:
      type: object
      properties:
        create:
          type: boolean
          description: Whether to create an Eraser file from the generated diagram
        linkAccess:
          $ref: '#/components/schemas/LinkAccess'

    InlineCodeEdit:
      type: object
      required:
        - code
        - diagramType
      properties:
        code:
          type: string
          description: Existing diagram code to edit
        diagramType:
          $ref: '#/components/schemas/DiagramTypeWithFreeform'

    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)

    GeneratedDiagram:
      type: object
      properties:
        diagramType:
          $ref: '#/components/schemas/DiagramTypeWithFreeform'
        code:
          type: string
          description: Generated Eraser DSL code

    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)

    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)

    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)

    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)

    AiRequestInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
            - attachment
            - context
            - repository
        text:
          type: string
          description: Text input (when type is 'text')
        storageId:
          type: string
          description: Storage ID for attachment (when type is 'attachment')
        filename:
          type: string
          description: Filename for attachment (when type is 'attachment')
        mimeType:
          type: string
          description: MIME type for attachment (when type is 'attachment')
        contextId:
          type: string
          description: Context ID (when type is 'context')
        repository:
          type: string
          description: Repository name (when type is 'repository')
        organization:
          type: string
          description: Organization name (when type is 'repository')
        provider:
          type: string
          description: Git provider (when type is 'repository')

    AiRequestOutput:
      type: object
      properties:
        type:
          type: string
          enum: [diagram]
        diagramType:
          $ref: '#/components/schemas/DiagramType'
        code:
          type: string
          description: Eraser DSL code
        diagramTitle:
          type: string
          description: Title of the generated diagram
        imageUrl:
          type: string
          description: URL of the rendered PNG image

    AiRequest:
      type: object
      properties:
        id:
          type: string
          description: Unique AI request identifier
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/AiRequestInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/AiRequestOutput'
        mode:
          type: string
          enum:
            - standard
            - premium
          description: AI model tier used

    CreateFileRequest:
      type: object
      properties:
        title:
          type: string
          description: Title of the file. Defaults to "Untitled".
        folderId:
          type: string
          description: Identifier for the folder destination
        document:
          type: string
          description: Markdown content for the file's document. Supports diagram code blocks.
        linkAccess:
          $ref: '#/components/schemas/LinkAccess'
        elements:
          type: array
          items:
            $ref: '#/components/schemas/CanvasElement'
          description: Canvas elements (diagrams, shapes, etc.)

    UpdateFileRequest:
      type: object
      properties:
        title:
          type: string
          description: New title for the file
        folderId:
          type: string
          description: ID of the folder to move the file to
        document:
          type: string
          description: New markdown content. Supports diagram code blocks converted to embedded diagrams.

    ArchiveFileResponse:
      type: object
      required:
        - archived
        - fileUrl
      properties:
        archived:
          type: boolean
          description: Whether the file was successfully archived
        fileUrl:
          type: string
          description: URL of the archived file

    CreateDiagramRequest:
      type: object
      required:
        - diagramType
      properties:
        diagramType:
          $ref: '#/components/schemas/DiagramType'
        code:
          type: string
          description: Eraser DSL code for the diagram. If omitted, creates an empty diagram.

    UpdateDiagramRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: New Eraser DSL code for the diagram

    DeleteDiagramResponse:
      type: object
      required:
        - deleted
        - fileUrl
      properties:
        deleted:
          type: boolean
          description: Whether the diagram was successfully deleted
        fileUrl:
          type: string
          description: URL of the containing file

    CreateFolderRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Folder name
        parentFolderId:
          type: string
          nullable: true
          description: Parent folder ID, or null for root-level
        order:
          type: integer
          description: Sort order among siblings. Auto-assigned if omitted.

    CreateFolderResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: ID of the created folder

    UpdateFolderRequest:
      type: object
      properties:
        name:
          type: string
          description: New folder name
        parentFolderId:
          type: string
          nullable: true
          description: New parent folder ID, or null for root

    SuccessResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: Whether the operation was successful

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong