2020-05-24 15:00:16 -04:00
openapi : 3.0 .3
2022-01-23 16:02:58 -05:00
info :
title : CodiMD
description : CodiMD is an open source collaborative note editor. Several tasks of CodiMD can be automated through this API.
2020-05-24 15:00:16 -04:00
version : 2.0 .0
2022-01-23 16:02:58 -05:00
contact :
name : CodiMD on GitHub
url : https://github.com/codimd/server
license :
name : AGPLv3
url : https://github.com/codimd/server/blob/master/LICENSE
externalDocs :
2020-05-24 15:00:16 -04:00
description : CodiMD Documentation
url : https://github.com/codimd/server/tree/master/docs
servers :
- url : "/api/v2.0/"
description : "Base API Path"
2022-01-23 16:02:58 -05:00
paths :
2020-05-24 15:00:16 -04:00
/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"
2022-01-23 16:02:58 -05:00
/new :
get :
tags :
- note
summary : Creates a new note.
2020-05-24 15:00:16 -04:00
operationId : createNote
2022-01-23 16:02:58 -05:00
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 :
2020-05-24 15:00:16 -04:00
200 :
description : Get information about the newly created note
content :
application/json :
schema :
"$ref": "#/components/schemas/NewNote"
2022-01-23 16:02:58 -05:00
post :
tags :
- note
summary : Imports some markdown data into a new note.
2020-05-24 15:00:16 -04:00
operationId : createNoteFromMarkdown
2022-01-23 16:02:58 -05:00
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' :
2020-05-24 15:00:16 -04:00
schema :
type : string
examples :
markdownExample :
"$ref": '#/components/examples/markdownExample'
2022-01-23 16:02:58 -05:00
responses :
2020-05-24 15:00:16 -04:00
200 :
description : Get information about the newly created note
content :
application/json :
schema :
"$ref": "#/components/schemas/NewNote"
2022-01-23 16:02:58 -05:00
/new/{alias}:
post :
tags :
- note
summary : Imports some markdown data into a new note with a given alias.
2020-05-24 15:00:16 -04:00
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.'
2022-01-23 16:02:58 -05:00
requestBody :
required : true
description : The content of the note to be imported as markdown
content :
'text/markdown' :
2020-05-24 15:00:16 -04:00
schema :
type : string
examples :
markdownExample :
"$ref": '#/components/examples/markdownExample'
2022-01-23 16:02:58 -05:00
responses :
2020-05-24 15:00:16 -04:00
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
2022-01-23 16:02:58 -05:00
parameters :
2020-05-24 15:00:16 -04:00
- name : alias
2022-01-23 16:02:58 -05:00
in : path
required : true
description : The alias for the note-id under which the note will be saved
content :
2020-05-24 15:00:16 -04:00
text/plain :
2022-01-23 16:02:58 -05:00
example : my-note
2020-05-25 06:04:29 -04:00
/n/{note}:
2022-01-23 16:02:58 -05:00
get :
tags :
- note
2020-05-25 06:04:29 -04:00
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
/n/{note}/export/markdown:
get :
tags :
- note
- export
2022-01-23 16:02:58 -05:00
summary : Returns the raw markdown content of a note.
2020-05-24 15:00:16 -04:00
operationId : getNoteContent
2020-05-25 06:04:29 -04:00
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 for which the revision should be shown
content :
text/plain :
example : my-note
/n/{note}/export/html:
get :
tags :
- note
- export
summary : Returns the content of a note as HTML.
operationId : getNoteContentAsHTML
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 for which the revision should be shown
content :
text/plain :
example : my-note
/n/{note}/export/gist:
get :
tags :
- note
- export
summary : Exports the content of a note to a gist.
operationId : exportNoteToGist
2022-01-23 16:02:58 -05:00
responses :
200 :
description : The raw markdown content of the note
content :
'text/markdown' :
2020-05-24 15:00:16 -04:00
schema :
type : string
examples :
markdownExample :
"$ref": '#/components/examples/markdownExample'
2022-01-23 16:02:58 -05:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
2020-05-24 15:00:16 -04:00
description : The note which should be downloaded
2022-01-23 16:02:58 -05:00
content :
2020-05-24 15:00:16 -04:00
text/plain :
2022-01-23 16:02:58 -05:00
example : my-note
2020-05-25 06:04:29 -04:00
/n/{note}/export/dropbox:
get :
tags :
- note
- export
summary : Exports the content of a note to dropbox.
operationId : exportNoteToDropbox
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
/n/{note}/info:
2022-01-23 16:02:58 -05:00
get :
tags :
- note
summary : Returns metadata about the note.
2020-05-24 15:00:16 -04:00
operationId : getNoteInfo
2022-01-23 16:02:58 -05:00
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 :
2020-05-24 15:00:16 -04:00
application/json :
2022-01-23 16:02:58 -05:00
schema :
2020-05-24 15:00:16 -04:00
"$ref": "#/components/schemas/NoteInfo"
2022-01-23 16:02:58 -05:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
description : The note for which the info should be shown
content :
2020-05-24 15:00:16 -04:00
text/plain :
2022-01-23 16:02:58 -05:00
example : my-note
2020-05-25 06:04:29 -04:00
/n/{note}/revision:
2022-01-23 16:02:58 -05:00
get :
tags :
- note
summary : Returns a list of the available note revisions.
2020-05-24 15:00:16 -04:00
operationId : getAllRevisionsOfNote
2022-01-23 16:02:58 -05:00
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 :
2020-05-24 15:00:16 -04:00
application/json :
2022-01-23 16:02:58 -05:00
schema :
2020-05-24 15:00:16 -04:00
"$ref": "#/components/schemas/NoteRevisionsMetadata"
2022-01-23 16:02:58 -05:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
description : The note for which revisions should be shown
content :
2020-05-24 15:00:16 -04:00
text/plain :
2022-01-23 16:02:58 -05:00
example : my-note
2020-05-25 06:04:29 -04:00
/n/{note}/revision/{revision-id}:
2022-01-23 16:02:58 -05:00
get :
tags :
- note
summary : Returns the revision of the note with some metadata.
2020-05-24 15:00:16 -04:00
operationId : getSpecificRevisionOfNote
2022-01-23 16:02:58 -05:00
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 :
2020-05-24 15:00:16 -04:00
application/json :
2022-01-23 16:02:58 -05:00
schema :
2020-05-24 15:00:16 -04:00
"$ref": "#/components/schemas/NoteRevision"
2022-01-23 16:02:58 -05:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
description : The note for which the revision should be shown
content :
2020-05-24 15:00:16 -04:00
text/plain :
2022-01-23 16:02:58 -05:00
example : my-note
- name : revision-id
in : path
required : true
description : The id (timestamp) of the revision to fetch
content :
2020-05-24 15:00:16 -04:00
text/plain :
2022-01-23 16:02:58 -05:00
example : 1570921051959
2020-05-24 15:00:16 -04:00
components :
schemas :
UserInfo :
type : object
properties :
id :
type : string
format : UUIDv4
name :
type : string
photo :
type : string
format : uri
2020-05-25 06:04:29 -04:00
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.
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
2020-05-24 15:00:16 -04:00
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 :
2022-01-23 16:02:58 -05:00
content :
2020-05-24 15:00:16 -04:00
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