openapi: 3.0.3
info:
  title: HedgeDoc
  description: HedgeDoc is an open source collaborative note editor. Several tasks of HedgeDoc can be automated through this API.
  version: 2.0.0
  contact:
    name: HedgeDoc on GitHub
    url: https://github.com/codimd/server
  license:
    name: AGPLv3
    url: https://github.com/codimd/server/blob/master/LICENSE
externalDocs:
  description: The CodiMD Documentation.
  url: https://github.com/codimd/server/tree/master/docs
servers:
  - url: "/api/v2"
    description: The base API Path.
security:
  - bearerAuth: []
paths:
  /me:
    get:
      tags:
        - user
      summary: Get the user information of the currently logged-in user
      operationId: getMe
      responses:
        '200':
          description: The user information.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UserInfo"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
  /me/history:
    get:
      tags:
        - history
        - user
      summary: Returns a list of the last viewed notes
      operationId: getHistory
      description: The list is returned as a JSON object with an array containing for each entry it's id, title, tags, last visit time and pinned status.
      responses:
        '200':
          description: The list of recently viewed notes and pinned notes.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/History"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
  /me/history/{note}:
    get:
      tags:
        - history
        - user
      summary: Returns History data for a note
      operationId: getHistoryObject
      description: JSON Object which contains id, title, tags, last visit time and pinned status
      responses:
        '200':
          description: The list of recently viewed notes and pinned notes.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HistoryObject"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The name of the note which is used to address it.
          content:
            text/plain:
              example: my-note
    put:
      tags:
        - history
        - user
      summary: Update the history object of the note (e.g change it's pin status)
      operationId: updateHistoryObject
      requestBody:
        description: The updated history object.
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/HistoryObject"
      responses:
        '200':
          description: The new history.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HistoryObject"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the revision should be shown.
          content:
            text/plain:
              example: my-note
    delete:
      tags:
        - history
        - user
      summary: Remove the note from the currently logged-in user's history
      operationId: deleteHistoryObject
      responses:
        '204':
          "$ref": "#/components/responses/SuccessfullyDeleted"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the revision should be shown.
          content:
            text/plain:
              example: my-note
  /me/notes:
    get:
      tags:
        - user
      summary: Returns a list of the notes metadata the user owns
      operationId: getOwnNotes
      description: The list is returned as a JSON object with an array containing each notes metadata.
      responses:
        '200':
          description: The list of notes owned by the currently logged in user.
          content:
            application/json:
              schema:
                type: array
                description: The array that contains notes metadata.
                items:
                  "$ref": "#/components/schemas/NoteMetadata"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
  /notes:
    post:
      tags:
        - note
      summary: Imports some markdown data into a new note
      operationId: createNoteFromMarkdown
      description: A random id will be assigned and the content will equal to the body of the received HTTP-request.
      security:
        - bearerAuth: []
        - {}
      requestBody:
        required: false
        description: The content of the note to be imported as markdown.
        content:
          'text/markdown':
            schema:
              type: string
            examples:
              markdownExample:
                "$ref": '#/components/examples/markdownExample'
      responses:
        '200':
          description: Get information about the newly created note.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Note"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
  /notes/{note}:
    get:
      tags:
        - note
      summary: Returns the note
      operationId: getNote
      description: This includes all metadata and the content of the note.
      responses:
        '200':
          description: All data of the note.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Note"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The name of the note which is used to address it.
          content:
            text/plain:
              example: my-note
    post:
      tags:
        - note
      summary: Imports some markdown data into a new note with a given alias
      operationId: createNoteWithAlias
      description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/configuration-env-vars.md#users-and-privileges) is enabled.
      requestBody:
        required: true
        description: The content of the note to be imported as markdown.
        content:
          'text/markdown':
            schema:
              type: string
            examples:
              markdownExample:
                "$ref": '#/components/examples/markdownExample'
      responses:
        '200':
          description: Get information about the newly created note.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Note"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '409':
          description: This alias is already in use.
      parameters:
        - name: note
          in: path
          required: true
          description: The name of the note which is used to address it.
          content:
            text/plain:
              example: my-note
    delete:
      tags:
        - note
      summary: Remove the note
      operationId: deleteNote
      responses:
        '204':
          "$ref": "#/components/responses/SuccessfullyDeleted"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the revision should be shown.
          content:
            text/plain:
              example: my-note
    put:
      tags:
        - note
      summary: Imports some markdown data into an existing note, creating a new revision
      operationId: createNewRevisionForNote
      description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/configuration-env-vars.md#users-and-privileges) is enabled.
      requestBody:
        required: true
        description: The content of the note to be imported as markdown.
        content:
          'text/markdown':
            schema:
              type: string
            examples:
              markdownExample:
                "$ref": '#/components/examples/markdownExample'
      responses:
        '200':
          description: The new, changed note
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Note"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the info should be shown.
          content:
            text/plain:
              example: my-note
  /notes/{note}/metadata:
    put:
      tags:
        - note
      summary: Set the permissions of a note
      operationId: updateNoteMetadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NoteMetadata"
      responses:
        '200':
          description: The updated permissions of the note.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NoteMetadata"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the info should be shown.
          content:
            text/plain:
              example: my-note
    get:
      tags:
        - note
      summary: Get the permissions of a note
      operationId: getNoteMetadata
      responses:
        '200':
          description: The permissions of the note.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NoteMetadata"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the info should be shown.
          content:
            text/plain:
              example: my-note
  /notes/{note}/revisions:
    get:
      tags:
        - note
      summary: Returns a list of the available note revisions
      operationId: getAllRevisionsOfNote
      description: The list contains the revision-id, the length and a ISO-timestamp of the creation date.
      responses:
        '200':
          description: Revisions of the note.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NoteRevisionsMetadata"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which revisions should be shown.
          content:
            text/plain:
              example: my-note
  /notes/{note}/revisions/{revision-id}:
    get:
      tags:
        - note
      summary: Returns the revision of the note with some metadata
      operationId: getSpecificRevisionOfNote
      description: The revision is returned as a JSON object with the content of the note and the authorship.
      responses:
        '200':
          description: Revision of the note for the given id.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NoteRevision"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the revision should be shown.
          content:
            text/plain:
              example: my-note
        - name: revision-id
          in: path
          required: true
          description: The id of the revision to fetch.
          content:
            text/plain:
              example: 1570921051959
  /notes/{note}/content:
    get:
      tags:
        - note
        - export
      summary: Returns the raw markdown content of a note
      operationId: getNoteContent
      responses:
        '200':
          description: The raw markdown content of the note.
          content:
            'text/markdown':
              schema:
                type: string
                format: binary
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
        '404':
          "$ref": "#/components/responses/NotFoundError"
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the markdown should be exported.
          content:
            text/plain:
              example: my-note
  /media/upload:
    post:
      tags:
        - media
      summary: Uploads a media file to the backend storage
      description: Uploads a file to be processed by the backend.
      requestBody:
        required: true
        description: The binary file to upload.
        content:
          application/pdf:
            schema:
              type: string
              format: binary
          image/apng:
            schema:
              type: string
              format: binary
          image/bmp:
            schema:
              type: string
              format: binary
          image/gif:
            schema:
              type: string
              format: binary
          image/heif:
            schema:
              type: string
              format: binary
          image/heic:
            schema:
              type: string
              format: binary
          image/heif-sequence:
            schema:
              type: string
              format: binary
          image/heic-sequence:
            schema:
              type: string
              format: binary
          image/jpeg:
            schema:
              type: string
              format: binary
          image/png:
            schema:
              type: string
              format: binary
          image/svg+xml:
            schema:
              type: string
              format: binary
          image/tiff:
            schema:
              type: string
              format: binary
          image/webp:
            schema:
              type: string
              format: binary
      parameters:
        - in: header
          name: HedgeDoc-Note
          schema:
            type: string
          required: true
          description: ID or alias of the parent note
      responses:
        '200':
          description: The file was uploaded successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
  /monitoring:
    get:
      tags:
        - monitoring
      summary: Returns the current status of the backend
      operationId: getMonitoring
      description: The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more.
      responses:
        '200':
          description: The server info.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ServerStatus"
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
  /monitoring/prometheus:
    get:
      tags:
        - monitoring
      summary: Returns the current status of the backend for Prometheus.
      operationId: getPrometheus
      description: The data is returned in Prometheus Exposition Format
      responses:
        '200':
          description: Prometheus compatible monitoring data.
          content:
            text/plain: {}
        '401':
          "$ref": "#/components/responses/UnauthorizedError"
        '403':
          "$ref": "#/components/responses/ForbiddenError"
components:
  schemas:
    UserInfo:
      type: object
      properties:
        userName:
          type: string
        displayName:
          type: string
        photo:
          type: string
          format: uri
        email:
          type: string
          format: email
    UserPasswordChange:
      type: object
      properties:
        password:
          type: string
    ImageProxyRequest:
      type: object
      properties:
        src:
          type: string
          description: The url of the image that should be processed by the image proxy.
    ImageProxyResponse:
      type: object
      properties:
        src:
          type: string
          description: The url of the provied version of the image.
    Note:
      type: object
      properties:
        content:
          type: string
          description: The markdown content of the note
        metadata:
          $ref: "#/components/schemas/NoteMetadata"
        editedByAtPosition:
          type: array
          description: Data which gives insights about who worked where on the note.
          items:
            type: integer
            description: Unique user ids and additional data
    NoteMetadata:
      type: object
      properties:
        id:
          type: string
          format: UUIDv4
          description: The id of the note.
        alias:
          type: string
          description: The alias of the note.
        title:
          type: string
          description: Title of the note
        description:
          type: string
          description: Description of the note.
        tags:
          type: array
          description: A list of tags attached to the note.
          items:
            type: string
            description: A tag
        updateTime:
          type: string
          description: ISO-timestamp of when the note was last changed.
        updateUser:
          $ref: "#/components/schemas/UserInfo"
        viewCount:
          type: integer
          minimum: 0
          description: How often the published version of the note was viewed.
        createTime:
          type: string
          description: The ISO-timestamp when the note was created in ISO 8601 format.
        editedBy:
          type: array
          description: List of usernames who edited the note.
          items:
            type: string
        permissions:
          $ref: "#/components/schemas/NotePermissions"
    NotePermissions:
      type: object
      properties:
        owner:
          type: string
          description: Username of the owner of the note
        sharedTo:
          type: array
          description: Contains all usernames that can read the note and a boolean that denotes if they can also edit.
          items:
            type: object
            properties:
              username:
                type: string
              canEdit:
                type: boolean

    NoteRevisionsMetadata:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
            description: The id of the revision
          createdTime:
            type: string
            description: ISO-timestamp of when the revision was saved. Is also the revision-id.
          length:
            type: integer
            description: Length of the document to the timepoint the revision was saved.
    NoteRevision:
      type: object
      properties:
        content:
          type: string
          description: The raw markdown content of the note revision.
        authorship:
          type: array
          description: Data which gives insights about who worked on the note.
          items:
            type: integer
            description: Unique user ids and additional data.
        patch:
          type: array
          description: Data which gives insight about what changed in comparison to former revisions.
          items:
            type: string
    GistLink:
      type: object
      properties:
        link:
          type: string
          format: uri
          description: A Gist link.
    DropboxLink:
      type: object
      properties:
        link:
          type: string
          format: uri
          description: A Dropbox link.
    EmailLogin:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
    LdapLogin:
      type: object
      properties:
        username:
          type: string
          format: email
        password:
          type: string
          format: password
    OpenIdLogin:
      type: object
      properties:
        openId:
          type: string
    ServerStatus:
      type: object
      properties:
        serverVersion:
          type: object
          properties:
            major:
              type: integer
            minor:
              type: integer
            patch:
              type: integer
            preRelease:
              type: string
            commit:
              type: string
          description: Version of the server specified according to SemVer specification
        onlineNotes:
          type: integer
          description: How many notes are edited at the moment.
        onlineUsers:
          type: integer
          description: How many users are online at the moment.
        distinctOnlineUsers:
          type: integer
          description: How many distinct users (different machines) are online at the moment.
        notesCount:
          type: integer
          description: How many notes are stored on the server.
        registeredUsers:
          type: integer
          description: How many users are registered on the server.
        onlineRegisteredUsers:
          type: integer
          description: How many of the online users are registered on the server.
        distinctOnlineRegisteredUsers:
          type: integer
          description: How many of the distinct online users are registered on the server.
        isConnectionBusy:
          type: boolean
        connectionSocketQueueLength:
          type: integer
        isDisconnectBusy:
          type: boolean
        disconnectSocketQueueLength:
          type: integer
    HistoryObject:
      type: object
      properties:
        metadata:
          $ref: "#/components/schemas/NoteMetadata"
        pinned:
          type: boolean
          description: Whether the user has pinned this note.
    History:
      type: object
      properties:
        history:
          type: array
          description: The array that contains history objects.
          items:
            "$ref": "#/components/schemas/HistoryObject"
  examples:
    markdownExample:
      value: '# Some header\nSome normal text. **Some bold text**'
      summary: A sample markdown content
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  responses:
    UnauthorizedError:
      description: Authorization information is missing or invalid.
    ForbiddenError:
      description: Access to the requested resource is not permitted.
    NotFoundError:
      description: The requested resource was not found.
    SuccessfullyDeleted:
      description: The requested resource was sucessfully deleted.