openapi: 3.0.3
info:
  title: CodiMD
  description: CodiMD is an open source collaborative note editor. Several tasks of CodiMD can be automated through this API.
  version: 2.0.0
  contact:
    name: CodiMD on GitHub
    url: https://github.com/codimd/server
  license:
    name: AGPLv3
    url: https://github.com/codimd/server/blob/master/LICENSE
externalDocs:
  description: CodiMD Documentation
  url: https://github.com/codimd/server/tree/master/docs
servers:
  - url: "/api/v2.0/"
    description: "Base API Path"
paths:
  /auth/email:
    post:
      tags:
        - auth
      summary: Trying to login via email
      operationId: loginEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailLogin'
      responses:
        '200':
          description: login succesful
          headers:
            Set-Cookie:
              schema:
                type: string
  /auth/ldap:
    post:
      tags:
        - auth
      summary: Trying to login via LDAP
      operationId: loginLdap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LdapLogin'
      responses:
        '200':
          description: login succesful
          headers:
            Set-Cookie:
              schema:
                type: string
  /auth/openid:
    post:
      tags:
        - auth
      summary: Trying to login via OpenID
      operationId: loginOpenId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenIdLogin'
      responses:
        '200':
          description: login succesful
          headers:
            Set-Cookie:
              schema:
                type: string
  /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':
          description: the user is not logged in
          content: {}
    post:
      tags:
        - user
      summary: Update information about the currently logged-in user
      operationId: updateMe
      responses:
        '200':
          description: The user information was changed successfully
      requestBody:
        required: true
        description: The new user information
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserUpdate"
    delete:
      tags:
        - user
      summary: "Deletes the currently logged-in user from the system and removes all it's notes"
      operationId: deleteMe
      responses:
        '200':
          description: The user was deleted successfully
  /me/export:
    get:
      tags:
        - user
        - export
      summary: Exports a zip-archive with all notes of the current user.
      responses:
        '200':
          description: The zip-archive with all notes
  /me/password:
    post:
      tags:
        - user
      summary: Sets the new password of a user
      requestBody:
        required: true
        description: The new password of the user
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UserPasswordChange"
      responses:
        '200':
          description: The password was changed
  /status:
    get:
      tags:
        - server
      summary: Returns the current status of the CodiMD instance.
      operationId: getStatus
      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"
  /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.
      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"
  /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"
        '404':
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the info should be shown
          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"
        '409':
          description: This alias is already in use
      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}/permissions:
    put:
      tags:
        - note
      summary: Set the permissions of a note
      operationId: updateNotePermissions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NotePermissions"
      responses:
        '200':
          description: The updated permissions of the note
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NotePermissions"
      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: getNotePermissions
      responses:
        '200':
          description: The permissions of the note
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NotePermissions"
      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}/export/markdown:
    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
        '404':
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the markdown should be exported
          content:
            text/plain:
              example: my-note
  /notes/{note}/export/html:
    get:
      tags:
        - note
        - export
      summary: Returns the content of a note as HTML.
      operationId: getNoteContentAsHTML
      responses:
        '200':
          description: The raw html content of the note
          content:
            'text/html':
              schema:
                type: string
                format: binary
        '404':
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the html should be exported
          content:
            text/plain:
              example: my-note
  /notes/{note}/export/gist:
    get:
      tags:
        - note
        - export
      summary: Exports the content of a note to a gist.
      operationId: exportNoteToGist
      responses:
        '200':
          description: The link to Gist of the note
          content:
            application/json:
              schema:
                "$ref": '#/components/schemas/GistLink'
        '404':
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note which should be exported to gist
          content:
            text/plain:
              example: my-note
  /notes/{note}/export/dropbox:
    get:
      tags:
        - note
        - export
      summary: Exports the content of a note to dropbox.
      operationId: exportNoteToDropbox
      responses:
        '200':
          description: The dropbox link of the note
          content:
            application/json:
              schema:
                "$ref": '#/components/schemas/DropboxLink'
        '404':
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note which should be exported to dropbox
          content:
            text/plain:
              example: my-note
  /notes/{note}/export/pdf:
    get:
      tags:
        - note
        - export
      summary: Exports the content of a note as PDF.
      operationId: exportNoteToPDF
      responses:
        '200':
          description: The note as an PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note which should be exported to dropbox
          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 is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved.
      responses:
        '200':
          description: Revisions of the note
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NoteRevisionsMetadata"
        '404':
          description: Note does not exist
      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 timestamp
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NoteRevision"
        '404':
          description: Note does not exist
      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 (timestamp) of the revision to fetch
          content:
            text/plain:
              example: 1570921051959
  /history:
    get:
      tags:
        - history
      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"
    post:
      tags:
        - history
      summary: Sets the history if none is already set
      operationId: updateHistory
      requestBody:
        description: The history to update
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/History"
      responses:
        '200':
          description: The new history
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/History"
    delete:
      tags:
        - history
      summary: Clear the users history
      operationId: deleteHistory
      responses:
        '200':
          description: Deleted the history
          content: {}
  /history/{note}:
    put:
      tags:
        - history
      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"
      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
      summary: Remove the history object of the note
      operationId: deleteHistoryObject
      responses:
        '200':
          description: The new history
          content: {}
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the revision should be shown
          content:
            text/plain:
              example: my-note
  /config:
    get:
      tags:
        - config
      summary: The config of the backend
      operationId: getConfig
      responses:
        '200':
          description: The config
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Config"
components:
  schemas:
    UserInfo:
      type: object
      properties:
        id:
          type: string
          format: UUIDv4
        name:
          type: string
        photo:
          type: string
          format: uri
        provider:
          type: string
          enum: ['facebook', 'github', 'twitter', 'gitlab', 'dropbox', 'google', 'saml', 'oauth2', 'email', 'ldap', 'openid']
    UserPasswordChange:
      type: object
      properties:
        password:
          type: string
    UserUpdate:
      type: object
      properties:
        name:
          type: string
          description: The new display name of the user
    Config:
      type: object
      properties:
        allowAnonymous:
          type: boolean
          description: Wether anonymous notes are allowed
        authProviders:
          type: object
          properties:
            facebook:
              type: boolean
              description: Wether Facebook login is possible
            github:
              type: boolean
              description: Wether GitHub login is possible
            twitter:
              type: boolean
              description: Wether Twitter login is possible
            gitlab:
              type: boolean
              description: Wether Gitlab login is possible
            dropbox:
              type: boolean
              description: Wether Dropbox login is possible
            google:
              type: boolean
              description: Wether Google login is possible
            saml:
              type: boolean
              description: Wether SAML login is possible
            oauth2:
              type: boolean
              description: Wether OAuth2 login is possible
            email:
              type: boolean
              description: Wether E-Mail login is possible
            ldap:
              type: boolean
              description: Wether LDAP login is possible
            openid:
              type: boolean
              description: Wether OpenID login is possible
        customAuthNames:
          type: object
          properties:
            ldap:
              type: string
              description: The custom name for the LDAP Login
              example: "FooBar LDAP"
            oauth2:
              type: string
              description: The custom name for the OAuth2 Login
              example: "Olaf2"
            saml:
              type: string
              description: The custom name for the SAML Login
              example: "aufSAMLn.de"
        specialLinks:
          type: object
          properties:
            privacy:
              type: string
              format: uri
              description: Link to the privacy notice
            termsOfUse:
              type: string
              format: uri
              description: Link to the terms of use
            imprint:
              type: string
              format: uri
              description: Link to the imprint
        version:
          type: object
          properties:
            version:
              type: string
            sourceCodeUrl:
              type: string
              format: uri
            issueTrackerUrl:
              type: string
              format: uri
    Note:
      type: object
      properties:
        id:
          type: string
          format: UUIDv4
          description: The id of the note
        alias:
          type: string
          description: The alias of the note
        lastChange:
          type: object
          properties:
            userId:
              type: string
              format: UUIDv4
              description: The id of the user that last changed the note
            user:
              type: string
              description: The name of the user that last changed the note
            timestamp:
              type: integer
              description: UNIX-timestamp of when the note was last changed.
        viewcount:
          type: integer
          minimum: 0
          description: How often the published version of the note was viewed
        createtime:
          type: string
          description: The timestamp when the note was created in ISO 8601 format.
        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
    NotePermissions:
      type: object
      properties:
        permission:
          type: string
          enum: ['freely', 'editable', 'limited', 'locked', 'protected', 'private']
    NoteRevisionsMetadata:
      type: object
      properties:
        revision:
          type: array
          description: Array that holds all revision-info objects
          items:
            type: object
            properties:
              time:
                type: integer
                description: UNIX-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:
        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:
        id:
          type: string
          description: The id or alias of the note
        title:
          type: string
          description: The title of the note
        lastVisited:
          type: integer
          description: The UNIX-timestamp in milliseconds when the note was last accessed by the user
        tags:
          type: array
          description: The tags that were added by the user to the note
          items:
            type: string
        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