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
          content: {}
  /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"
  /new:
    get:
      tags:
        - note
      summary: Creates a new note.
      operationId: createNote
      description: A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note.
      responses:
        200:
          description: Get information about the newly created note
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NewNote"
    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: 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"
  /new/{alias}:
    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: alias
          in: path
          required: true
          description: The alias for the note-id under which the note will be saved
          content:
            text/plain:
              example: my-note
  /{note}/download:
    get:
      tags:
        - note
      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
              examples:
                markdownExample:
                  "$ref": '#/components/examples/markdownExample'
        404:
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note which should be downloaded
          content:
            text/plain:
              example: my-note
  /{note}/info:
    get:
      tags:
        - note
      summary: Returns metadata about the note.
      operationId: getNoteInfo
      description: This includes the title and description of the note as well as the creation date and viewcount.
      responses:
        200:
          description: Metadata about the note
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/NoteInfo"
        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
  /{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

  /{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
    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
    NoteInfo:
      type: object
      properties:
        title:
          type: string
          description: The title of the note
          default: Untitled
        description:
          type: string
          description: The description of the note or the first words from the note
        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.
        updatetime:
          type: string
          description: The timestamp when the note was last updated in ISO 8601 format.
    EmailLogin:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
    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