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: {}
  /me/export:
    get:
      tags:
        - user
      summary: Exports a zip-archive with all notes of the current user.
      responses:
        200:
          description: The zip-archive with all notes
  /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/NewNote"
  /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/NewNote"
        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}/revision:
    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}/revision/{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
components:
  schemas:
    UserInfo:
      type: object
      properties:
        id:
          type: string
          format: UUIDv4
        name:
          type: string
        photo:
          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
    NewNote:
      type: object
      properties:
        id:
          type: string
          description: the id of the new note
          format: UUIDv4
        alias:
          type: string
          description: the alias with which the note should be accessed
    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
  examples:
    markdownExample:
      value: '# Some header\nSome normal text. **Some bold text**'
      summary: A sample markdown content