openapi: 3.0.0
info:
  title: Mermaid Chart
  description: |
    These are the subset of MermaidChart APIs that's required to create plugins to display diagrams for users.

    User authentication SHOULD be done using OAuth, with the PKCE flow.

    The clientID and redirectURL should be registered by submitting a request to the MermaidChart team.
  version: 0.1.0
tags:
  - name: user
    description: User details
  - name: project
    description: Project details
  - name: document
    description: Document details
servers:
  - url: https://mermaidchart.com
  - url: https://stage.mermaidchart.com

security:
  - mermaidchart_auth:
      - read
  - bearer_auth: []

components:
  schemas:
    User:
      type: object
      properties:
        fullName:
          type: string
        emailAddress:
          type: string
      required:
        - fullName
        - emailAddress
    Project:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
      required:
        - id
        - title
    Document:
      type: object
      description: |
        MermaidChart document that may contain a diagram.
      properties:
        projectID:
          type: string
        title:
          type: string
      required:
        - documentID
        - projectID
        - title
    DiagramDocument:
      type: object
      description: |
        MermaidChart diagram document, without any Document metadata.
      properties:
        documentID:
          description: |
            The id of the document that this diagram is linked to.
          type: string
          format: uuid
        major:
          type: integer
        minor:
          type: integer
        id:
          type: string
          format: uuid
          description: |
            The id of this diagram, required for `setDocument()`.
        code:
          type: string
          description: |
            The Mermaid
            [`application/vnd.mermaid`](https://www.iana.org/assignments/media-types/application/vnd.mermaid)
            code for this diagram.
      required:
        - documentID
        - id
    MCDocument:
      description: |
        MermaidChart diagram document.
      allOf:
        - $ref: "#/components/schemas/Document"
        - $ref: "#/components/schemas/DiagramDocument"

  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    mermaidchart_auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            read: Read data

paths:
  /rest-api/users/me:
    get:
      tags:
        - user
      summary: Get details of the user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /rest-api/projects:
    get:
      tags:
        - project
      summary: Get projects for the user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
  /rest-api/projects/{projectID}/documents:
    get:
      tags:
        - project
      summary: Get documents for a project
      parameters:
        - name: projectID
          in: path
          required: true
          description: The ID of the project to get documents for
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MCDocument'
    post:
      tags:
        - project
      summary: Add a new document to the project.
      operationId: createDocument
      parameters:
        - name: projectID
          in: path
          required: true
          description: The ID of the project to add a document to.
          schema:
            type: string
      requestBody:
        description: Currently unused, as long as it's not a form.
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: |
            The newly created diagram document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCDocument'

  /app/projects/{projectID}/diagrams/{documentID}/version/{version}:
    get:
      tags:
        - document
      summary: Get details for a document
      parameters:
        - name: projectID
          in: path
          required: true
          description: The ID of the project to get diagram data for
          schema:
            type: string
        - name: documentID
          in: path
          required: true
          description: The ID of the document to get diagram data for
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: The version of the document to get diagram data for
          schema:
            type: string
          example: v0.1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCDocument'

  /rest-api/documents/{documentID}:
    get:
      tags:
        - document
      summary: Gets the given diagram
      operationId: getDocument
      parameters:
        - name: documentID
          in: path
          required: true
          description: The ID of the document to get diagram data for
          schema:
            type: string
        - name: version
          in: query
          required: false
          description: |
            The version of the document to get diagram data for.

            If not set, defaults to the highest version.
          schema:
            type: string
          example: v0.1
      security:
        - mermaidchart_auth:
          - read
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCDocument'
        '404':
          description: File Not Found
    put:
      tags:
        - document
      summary: Update the given document.
      operationId: setDocument
      parameters:
        - name: documentID
          in: path
          required: true
          description: The ID of the document to update.
          schema:
            type: string
      requestBody:
        description: Document and diagram settings to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCDocument'
      security:
        - mermaidchart_auth: []
      responses:
        '200':
          description: |
            Update status.
          content:
            application/json:
              schema:
                type: object
                # TODO: update this once MC-1060 is fixed.
                # properties:
                #   result:
                #     type: string
                #     enum:
                #       - ok
                #       - failed
    delete:
      tags:
        - document
      summary: Delete the given document.
      operationId: deleteDocument
      parameters:
        - name: documentID
          in: path
          required: true
          description: The ID of the document to delete.
          schema:
            type: string
      security:
        - mermaidchart_auth: []
      responses:
        '200':
          description: The deleted document.
          content:
            application/json:
              schema:
                # currently only returns the document, no diagram data!!!!
                $ref: '#/components/schemas/Document'

  /raw/{documentID}:
    get:
      tags:
        - document
      summary: Get raw diagram data in SVG or PNG format
      parameters:
        - name: documentID
          in: path
          required: true
          description: The ID of the document to get raw data for
          schema:
            type: string
        - name: version
          in: query
          required: true
          description: The version of the document to get raw data for
          schema:
            type: string
          example: v0.1
        - name: theme
          in: query
          required: true
          description: The theme to use for the raw data
          schema:
            type: string
            enum:
              - light
              - dark
        - name: format
          in: query
          required: true
          description: The format of the raw data to return
          schema:
            type: string
            enum:
              - svg
              - png
      responses:
        '200':
          description: OK

  /app/projects/{projectID}/diagrams/{documentID}/version/{version}/edit:
    get:
      tags:
        - document
      summary: Edior URL to edit the diagram in the browser.
      parameters:
        - name: projectID
          in: path
          required: true
          description: The ID of the project to get diagram data for
          schema:
            type: string
        - name: documentID
          in: path
          required: true
          description: The ID of the document to get diagram data for
          schema:
            type: string
        - name: version
          in: path
          required: true
          description: The version of the document to get diagram data for
          schema:
            type: string
          example: v0.1
      responses:
        '200':
          description: OK